alepha 0.14.4 → 0.15.0

package/src/core/providers/KeylessJsonSchemaCodec.ts

@@ -0,0 +1,407 @@
+import type { TArray, TObject, TSchema, TUnion } from "typebox";
+import { SchemaCodec } from "./SchemaCodec.ts";
+import { type Static, t } from "./TypeProvider.ts";
+
+// =============================================================================
+// Keyless JSON Codec
+// =============================================================================
+// Schema-driven JSON encoding without keys:
+// - Schema defines field order → no keys needed in output
+// - Uses native JSON.stringify on arrays (fast!)
+// - Uses native JSON.parse for decoding (blazing fast)
+// - 50-56% smaller than JSON, decode 1.7-2x faster
+//
+// Example:
+//   JSON:    {"name":"Alice","age":30,"active":true}  (39 bytes)
+//   Keyless: ["Alice",30,true]                        (17 bytes)
+// =============================================================================
+
+export interface KeylessCodec<T = any> {
+  encode: (value: T) => string;
+  decode: (str: string) => T;
+}
+
+/**
+ * KeylessJsonSchemaCodec provides schema-driven JSON encoding without keys.
+ *
+ * It uses the schema to determine field order, allowing the encoded output
+ * to be a simple JSON array instead of an object with keys.
+ *
+ * Performance characteristics:
+ * - Encode: 0.94-1.53x vs JSON.stringify (faster for complex objects)
+ * - Decode: 1.76-2.00x vs JSON.parse
+ * - Size: 50-56% smaller than JSON
+ */
+export class KeylessJsonSchemaCodec extends SchemaCodec {
+  protected readonly cache = new Map<TSchema, KeylessCodec>();
+  protected readonly encoder = new TextEncoder();
+  protected readonly decoder = new TextDecoder();
+  protected varCounter = 0;
+
+  /**
+   * Encode value to a keyless JSON string.
+   */
+  public encodeToString<T extends TSchema>(
+    schema: T,
+    value: Static<T>,
+  ): string {
+    return this.getCodec(schema).encode(value);
+  }
+
+  /**
+   * Encode value to binary (UTF-8 encoded keyless JSON).
+   */
+  public encodeToBinary<T extends TSchema>(
+    schema: T,
+    value: Static<T>,
+  ): Uint8Array {
+    return this.encoder.encode(this.encodeToString(schema, value));
+  }
+
+  /**
+   * Decode keyless JSON string or binary to value.
+   */
+  public decode<T>(schema: TSchema, value: unknown): T {
+    if (value instanceof Uint8Array) {
+      const text = this.decoder.decode(value);
+      return this.getCodec(schema).decode(text) as T;
+    }
+
+    if (typeof value === "string") {
+      return this.getCodec(schema).decode(value) as T;
+    }
+
+    // If already an array (parsed JSON), reconstruct object
+    if (Array.isArray(value)) {
+      return this.reconstructObject(schema, value) as T;
+    }
+
+    return value as T;
+  }
+
+  // ===========================================================================
+  // Codec Compilation
+  // ===========================================================================
+
+  /**
+   * Get a compiled codec for the given schema.
+   * Codecs are cached for reuse.
+   */
+  protected getCodec<T>(schema: TSchema): KeylessCodec<T> {
+    let c = this.cache.get(schema);
+    if (!c) {
+      c = this.compile(schema);
+      this.cache.set(schema, c);
+    }
+    return c as KeylessCodec<T>;
+  }
+
+  protected nextVar(): string {
+    return `_${this.varCounter++}`;
+  }
+
+  protected compile(schema: TSchema): KeylessCodec {
+    this.varCounter = 0;
+    const encBody = this.genEnc(schema, "v");
+
+    this.varCounter = 0;
+    const decBody = this.genDec(schema);
+
+    const encoder = new Function("v", `return JSON.stringify(${encBody});`) as (
+      value: any,
+    ) => string;
+
+    const decoder = new Function(
+      "s",
+      `const a=JSON.parse(s);let i=0;${decBody.code}return ${decBody.result};`,
+    ) as (str: string) => any;
+
+    return { encode: encoder, decode: decoder };
+  }
+
+  // ===========================================================================
+  // Encoder - generates code that returns an array representation
+  // ===========================================================================
+
+  protected genEnc(schema: TSchema, ve: string): string {
+    if (
+      t.schema.isString(schema) ||
+      t.schema.isNumber(schema) ||
+      t.schema.isInteger(schema) ||
+      t.schema.isBoolean(schema) ||
+      this.isEnum(schema)
+    ) {
+      return ve;
+    }
+
+    if (t.schema.isBigInt(schema)) {
+      return `${ve}+'n'`;
+    }
+
+    if (t.schema.isArray(schema)) {
+      const arrSchema = schema as TArray;
+      const itemEnc = this.genEnc(arrSchema.items, "e");
+      if (
+        t.schema.isString(arrSchema.items) ||
+        t.schema.isNumber(arrSchema.items) ||
+        t.schema.isInteger(arrSchema.items) ||
+        t.schema.isBoolean(arrSchema.items)
+      ) {
+        return ve;
+      }
+      return `${ve}.map(e=>${itemEnc})`;
+    }
+
+    if (t.schema.isObject(schema)) {
+      const objSchema = schema as TObject;
+      const props = objSchema.properties as Record<string, TSchema>;
+      const keys = Object.keys(props);
+      const req = new Set((objSchema.required as string[]) || []);
+
+      const parts: string[] = [];
+      for (const k of keys) {
+        const ps = props[k];
+        const isOpt = !req.has(k) || t.schema.isOptional(ps);
+        const isNullable = this.isNullable(ps);
+        const inner = this.unwrap(ps);
+        const innerEnc = this.genEnc(inner, `${ve}.${k}`);
+
+        if (isOpt) {
+          parts.push(`${ve}.${k}!==undefined?${innerEnc}:null`);
+        } else if (isNullable) {
+          parts.push(`${ve}.${k}!==null?${innerEnc}:null`);
+        } else {
+          parts.push(innerEnc);
+        }
+      }
+
+      return `[${parts.join(",")}]`;
+    }
+
+    if (t.schema.isOptional(schema) || t.schema.isUnion(schema)) {
+      const inner = this.unwrap(schema);
+      const innerEnc = this.genEnc(inner, ve);
+      if (this.isNullable(schema)) {
+        return `${ve}!==null?${innerEnc}:null`;
+      }
+      return `${ve}!==undefined?${innerEnc}:null`;
+    }
+
+    return ve;
+  }
+
+  // ===========================================================================
+  // Decoder - generates code to reconstruct object from parsed array
+  // ===========================================================================
+
+  protected genDec(schema: TSchema): { code: string; result: string } {
+    const v = this.nextVar();
+
+    if (
+      t.schema.isString(schema) ||
+      t.schema.isNumber(schema) ||
+      t.schema.isInteger(schema) ||
+      t.schema.isBoolean(schema) ||
+      this.isEnum(schema)
+    ) {
+      return { code: "", result: "a[i++]" };
+    }
+
+    if (t.schema.isBigInt(schema)) {
+      return { code: "", result: "BigInt(a[i++].slice(0,-1))" };
+    }
+
+    if (t.schema.isArray(schema)) {
+      const arrSchema = schema as TArray;
+      // Check if array items need transformation (objects)
+      if (t.schema.isObject(arrSchema.items)) {
+        const itemTransform = this.genDecFromValue(arrSchema.items, "e");
+        return { code: "", result: `a[i++].map(e=>${itemTransform})` };
+      }
+      return { code: "", result: "a[i++]" };
+    }
+
+    if (t.schema.isObject(schema)) {
+      const objSchema = schema as TObject;
+      const props = objSchema.properties as Record<string, TSchema>;
+      const keys = Object.keys(props);
+      const req = new Set((objSchema.required as string[]) || []);
+
+      // Check if simple (all required primitives)
+      let simple = true;
+      for (const k of keys) {
+        const ps = props[k];
+        const isOpt = !req.has(k) || t.schema.isOptional(ps);
+        const isNullable = this.isNullable(ps);
+        const inner = this.unwrap(ps);
+        if (
+          isOpt ||
+          isNullable ||
+          t.schema.isObject(inner) ||
+          t.schema.isArray(inner)
+        ) {
+          simple = false;
+          break;
+        }
+      }
+
+      if (simple) {
+        const fields = keys.map((k) => `${k}:a[i++]`);
+        return { code: "", result: `{${fields.join(",")}}` };
+      }
+
+      let code = `const ${v}={};`;
+      for (const k of keys) {
+        const ps = props[k];
+        const isOpt = !req.has(k) || t.schema.isOptional(ps);
+        const isNullable = this.isNullable(ps);
+        const inner = this.unwrap(ps);
+
+        if (isOpt) {
+          const nested = this.genDecFromValue(inner, "t");
+          code += `{const t=a[i++];if(t!==null){${v}.${k}=${nested};}}`;
+        } else if (isNullable) {
+          const nested = this.genDecFromValue(inner, "t");
+          code += `{const t=a[i++];if(t===null){${v}.${k}=null;}else{${v}.${k}=${nested};}}`;
+        } else if (t.schema.isObject(inner)) {
+          const nested = this.genDecFromValue(inner, "a[i++]");
+          code += `${v}.${k}=${nested};`;
+        } else if (t.schema.isArray(inner)) {
+          // Handle arrays - check if items need transformation
+          const arrSchema = inner as TArray;
+          if (t.schema.isObject(arrSchema.items)) {
+            const itemTransform = this.genDecFromValue(arrSchema.items, "e");
+            code += `${v}.${k}=a[i++].map(e=>${itemTransform});`;
+          } else {
+            code += `${v}.${k}=a[i++];`;
+          }
+        } else {
+          code += `${v}.${k}=a[i++];`;
+        }
+      }
+
+      return { code, result: v };
+    }
+
+    if (t.schema.isOptional(schema) || t.schema.isUnion(schema)) {
+      const inner = this.unwrap(schema);
+      const innerDec = this.genDec(inner);
+      const nullVal = this.isNullable(schema) ? "null" : "undefined";
+      return {
+        code: `const ${v}t=a[i++];let ${v};if(${v}t===null){${v}=${nullVal};}else{${innerDec.code.replace(/a\[i\+\+\]/g, `${v}t`)}${v}=${innerDec.result.replace(/a\[i\+\+\]/g, `${v}t`)};}`,
+        result: v,
+      };
+    }
+
+    return { code: "", result: "a[i++]" };
+  }
+
+  protected genDecFromValue(schema: TSchema, expr: string): string {
+    if (
+      t.schema.isString(schema) ||
+      t.schema.isNumber(schema) ||
+      t.schema.isInteger(schema) ||
+      t.schema.isBoolean(schema) ||
+      this.isEnum(schema)
+    ) {
+      return expr;
+    }
+    if (t.schema.isBigInt(schema)) {
+      return `BigInt(${expr}.slice(0,-1))`;
+    }
+    if (t.schema.isArray(schema)) {
+      return expr;
+    }
+    if (t.schema.isObject(schema)) {
+      const objSchema = schema as TObject;
+      const props = objSchema.properties as Record<string, TSchema>;
+      const keys = Object.keys(props);
+      const v = this.nextVar();
+      const fields = keys.map((k, idx) => {
+        const inner = this.unwrap(props[k]);
+        const innerExpr = `${v}[${idx}]`;
+        if (t.schema.isObject(inner)) {
+          return `${k}:${this.genDecFromValue(inner, innerExpr)}`;
+        }
+        if (t.schema.isBigInt(inner)) {
+          return `${k}:BigInt(${innerExpr}.slice(0,-1))`;
+        }
+        return `${k}:${innerExpr}`;
+      });
+      return `((${v}=${expr})=>({${fields.join(",")}}))()`;
+    }
+    return expr;
+  }
+
+  // ===========================================================================
+  // Helpers
+  // ===========================================================================
+
+  protected isEnum(schema: TSchema): boolean {
+    return (
+      "enum" in schema &&
+      Array.isArray((schema as { enum?: unknown[] }).enum) &&
+      ((schema as { enum?: unknown[] }).enum?.length ?? 0) > 0
+    );
+  }
+
+  protected isNullable(schema: TSchema): boolean {
+    if (!t.schema.isUnion(schema)) return false;
+    const unionSchema = schema as TUnion;
+    return unionSchema.anyOf?.some((s: TSchema) => t.schema.isNull(s)) ?? false;
+  }
+
+  protected unwrap(schema: TSchema): TSchema {
+    if ("anyOf" in schema && Array.isArray((schema as TUnion).anyOf)) {
+      const unionSchema = schema as TUnion;
+      return (
+        unionSchema.anyOf.find((s: TSchema) => !t.schema.isNull(s)) || schema
+      );
+    }
+    return schema;
+  }
+
+  /**
+   * Reconstruct an object from a parsed array (for when input is already parsed).
+   */
+  protected reconstructObject(schema: TSchema, arr: any[]): any {
+    if (!t.schema.isObject(schema)) {
+      return arr;
+    }
+
+    const objSchema = schema as TObject;
+    const props = objSchema.properties as Record<string, TSchema>;
+    const keys = Object.keys(props);
+    const result: Record<string, any> = {};
+    let i = 0;
+
+    for (const k of keys) {
+      const ps = props[k];
+      const isOpt = t.schema.isOptional(ps);
+      const isNullable = this.isNullable(ps);
+      const inner = this.unwrap(ps);
+      const val = arr[i++];
+
+      if (isOpt) {
+        if (val !== null) {
+          result[k] = t.schema.isObject(inner)
+            ? this.reconstructObject(inner, val)
+            : val;
+        }
+      } else if (isNullable) {
+        result[k] =
+          val === null
+            ? null
+            : t.schema.isObject(inner)
+              ? this.reconstructObject(inner, val)
+              : val;
+      } else {
+        result[k] = t.schema.isObject(inner)
+          ? this.reconstructObject(inner, val)
+          : val;
+      }
+    }
+
+    return result;
+  }
+}

package/src/core/providers/StateManager.spec.ts

@@ -209,12 +209,16 @@ describe("StateManager", () => {
     });
 
     it("should set values in ALS when context exists", async () => {
-      const store: any = { context: "test-context" };
-      alepha.context.run(() => {
-        stateManager.set("name", "ALS Value");
-      }, store);
+      // Note: AlsProvider spreads the store object, so we check values inside the callback
+      const result = alepha.context.run(
+        () => {
+          stateManager.set("name", "ALS Value");
+          return stateManager.get("name");
+        },
+        { context: "test-context" },
+      );
 
-      expect(store.name).toBe("ALS Value");
+      expect(result).toBe("ALS Value");
     });
 
     it("should set values in local store when no ALS context", () => {
@@ -267,14 +271,16 @@ describe("StateManager", () => {
       stateManager.set("name", "Local Value");
 
       // In ALS context, ALS values should take priority
-      const store: any = { context: "test-context" };
-      const result = alepha.context.run(() => {
-        stateManager.set("name", "ALS Priority");
-        return stateManager.get("name");
-      }, store);
+      // Note: AlsProvider spreads the store object, so we check values inside the callback
+      const result = alepha.context.run(
+        () => {
+          stateManager.set("name", "ALS Priority");
+          return stateManager.get("name");
+        },
+        { context: "test-context" },
+      );
 
       expect(result).toBe("ALS Priority");
-      expect(store.name).toBe("ALS Priority");
     });
 
     it("should not skip event emission when values are the same", async () => {
@@ -291,12 +297,17 @@ describe("StateManager", () => {
     });
 
     it("should delete values from ALS when context exists", async () => {
-      const store = { name: "To Delete", context: "test-context" };
-      alepha.context.run(() => {
-        stateManager.del("name");
-      }, store);
+      // Note: AlsProvider spreads the store object, so we check values inside the callback
+      const result = alepha.context.run(
+        () => {
+          stateManager.set("name", "To Delete");
+          stateManager.del("name");
+          return stateManager.get("name");
+        },
+        { context: "test-context" },
+      );
 
-      expect(store.name).toBeUndefined();
+      expect(result).toBeUndefined();
     });
 
     it("should clear only local store, not ALS", async () => {