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.

---