TypeSalad

Adds more static typing and a C#-like structure to JavaScript without relying on TypeScript.

TypeSalad is a lightweight library that provides typed wrappers, metadata reflection, and convenience utilities for JavaScript. It includes classes such as SaladString, SaladInt, SaladBool, and more—emulating a statically typed style similar to C#, all while staying in pure JavaScript (no compile step required).

• GitHub: github.com/Git-cli-repo/TypeSalad

Table of Contents

1. Features
2. Installation
3. Usage
4. API Overview
   • Typed Classes
   • Helpers & Utilities
   • System Singleton
5. Extending TypeSalad (Packages)
6. Examples
7. Contributing
8. License

Features

• Typed Wrappers: Classes like SaladString, SaladInt, SaladBool, SaladDate, etc., each storing an internal value but maintaining a .type property.
• C#-like Syntax: Simulates typed structures and simple reflection (e.g., addMetadata, getMetadata, and QueryableArray).
• No Build Step Required: Pure JavaScript, no TypeScript config needed. Just import and go.
• Optional Event System: Provides a simple EventEmitter class for event-based programming.
• Extensible Architecture: A System singleton supports dynamically loading “packages” (e.g., SaladMath, SaladLinq, etc.) via ES modules for additional functionality.

Installation

npm install typesalad

(Requires Node.js to install.)

Usage

ES Module

import {
  System,
  SaladString,
  SaladInt,
  TypedIf
} from 'typesalad';

// Create typed values
const greeting = new SaladString('Hello, TypeSalad');
const numberOne = new SaladInt(1);
const numberTwo = new SaladInt(2);

// Print using System
System.Print(greeting); // Logs: "Hello, TypeSalad"

// Compare with TypedIf
TypedIf(
  numberOne,
  numberTwo,
  () => console.log('They are equal!'),
  () => console.log('They are not equal!')
);
// Logs: "They are not equal!"

CommonJS (if needed)

const {
  System,
  SaladString,
  SaladInt,
  TypedIf
} = require('typesalad');

(If your package.json has "type": "module", you’ll use ES Modules. Otherwise, CommonJS might be your default.)

API Overview

Typed Classes

• SaladString: Wraps a string.
• SaladInt: Wraps an integer.
• SaladFloat: Wraps a floating-point number.
• SaladBool: Wraps a boolean.
• SaladDate: Wraps a Date object.
• SaladArray: A typed, array-like structure.
• SaladObject: A typed, object-like structure.
• SaladVec2, SaladVec3: Vector classes for 2D/3D operations.

Each class has a .type property (e.g. "String", "Int", etc.) and methods like toString(), valueOf(), or other specialized methods.

Helpers & Utilities

• TypedIf(expr1, expr2, onEqual, onNotEqual): Checks if two typed objects share the same .type and .valueOf(), then invokes the appropriate callback.
• createGenericList(expectedType): Creates a class that enforces a specific type for all items added.
• QueryableArray: A chainable array wrapper with .where(), .select(), .orderBy(), etc.
• Overloadable: Allows defining multiple method overloads based on parameter types.
• addMetadata(obj, key, value) and getMetadata(obj, key): Simple reflection-like metadata storage.

System Singleton

• System (singleton):
  • Print(value): Logs typed strings.
  • Concat(expr1, expr2): Concatenates two typed values (String or Int).
  • StoreData(key, value) / RetData(key): Simple typed storage.
  • UsePackage(packageName, packagePath, exportName?): Dynamically imports a package and stores it under System.Packages.

Extending TypeSalad (Packages)

TypeSalad is designed to be easily extensible. You can create custom “packages” in separate .mjs files and load them via the built-in System.UsePackage() method.

By default, TypeSalad includes four optional “built-in” packages that demonstrate how to extend functionality:

1. SaladMath (imported as "SaladMath"):

   System.UsePackage("SaladMath", "./packages/SaladMath.mjs");
   // Then access with System.SaladMath

   • Exposes classes like ImagInt and Vector for complex arithmetic and vector math.

2. SaladLinq (imported as "SaladLinqPackage"):

   System.UsePackage("SaladLinq", "./packages/SaladLinq.mjs", "SaladLinqPackage");
   // Then access with System.SaladLinq

   • Provides chainable query operators (like a LINQ-inspired API).

3. SaladFiles (imported as "SaladFilesPackage"):

   System.UsePackage("SaladFiles", "./packages/SaladFiles.mjs", "SaladFilesPackage");
   // Then access with System.SaladFiles

   • Offers typed read/write for text and JSON files (Node.js environments).

4. SaladDOM (imported as "SaladDOMPackage"):

   System.UsePackage("SaladDOM", "./packages/SaladDOM.mjs", "SaladDOMPackage");
   // Then access with System.SaladDOM

   • Lets you create and manipulate DOM elements using typed wrappers in the browser.

You can create your own packages in a similar fashion—just export a class that extends TypeSalad (or uses typed objects) and load it via System.UsePackage("YourPackageName", "./path/YourPackage.mjs", "ExportedClassName").

Examples

1. Using SaladArray:

   import { SaladArray, SaladString } from 'typesalad';
   
   const arr = new SaladArray([
     new SaladString("Apple"),
     new SaladString("Banana")
   ]);
   
   arr.push(new SaladString("Cherry"));
   console.log(arr.length); // 3
   console.log(arr.toString()); // [Apple, Banana, Cherry]

2. Overloading Methods:

   import { Overloadable, SaladString, SaladInt } from 'typesalad';
   
   const myObj = new Overloadable();
   myObj.defineOverload('doSomething', ['String'], function(str) {
     return `Doing something with string: ${str}`;
   });
   
   myObj.defineOverload('doSomething', ['Int'], function(intVal) {
     return `Doing something with int: ${intVal}`;
   });
   
   console.log(myObj.callOverload('doSomething', new SaladString('Hello'))); 
   // => "Doing something with string: Hello"
   
   console.log(myObj.callOverload('doSomething', new SaladInt(42))); 
   // => "Doing something with int: 42"

3. Metadata Reflection:

   import { addMetadata, getMetadata } from 'typesalad';
   
   const user = {};
   addMetadata(user, 'role', 'admin');
   console.log(getMetadata(user, 'role')); // "admin"

4. Loading a Built-in Package:

   import { System, SaladInt } from 'typesalad';
   
   // Load SaladMath package
   await System.UsePackage("SaladMath", "./packages/SaladMath.mjs");
   const { add, multiply } = System.SaladMath;
   
   // Typed math operations
   const a = new SaladInt(3);
   const b = new SaladInt(4);
   const result = multiply(a, b); // => SaladInt(12)
   console.log(result.valueOf()); // 12

Contributing

Contributions are welcome! Here’s how you can help:

1. Fork the repository on GitHub and clone it locally.
2. Create a new branch with a descriptive name.
3. Make your changes, add new features or bug fixes, and (if possible) include tests.
4. Push to your fork and create a Pull Request.

Please file an issue if you find any bugs or have ideas for improvements.

License

This project is licensed under the MIT License. See the LICENSE file for details.