alepha 0.22.0 → 0.24.0

package/src/core/Alepha.ts

@@ -1,4 +1,3 @@
-import type { Record, Static, TObject } from "typebox";
 import { KIND } from "./constants/KIND.ts";
 import { MODULE } from "./constants/MODULE.ts";
 import { OPTIONS } from "./constants/OPTIONS.ts";
@@ -6,6 +5,7 @@ import { AlephaError } from "./errors/AlephaError.ts";
 import { CircularDependencyError } from "./errors/CircularDependencyError.ts";
 import { ContainerLockedError } from "./errors/ContainerLockedError.ts";
 import { TooLateSubstitutionError } from "./errors/TooLateSubstitutionError.ts";
+import { coerceObject } from "./helpers/coerceStrings.ts";
 import { Primitive } from "./helpers/primitive.ts";
 import { __alephaRef } from "./helpers/ref.ts";
 import type { Async } from "./interfaces/Async.ts";
@@ -18,13 +18,19 @@ import {
   type ServiceEntry,
 } from "./interfaces/Service.ts";
 import type { Atom, AtomStatic, TAtomObject } from "./primitives/$atom.ts";
+import type { Computed } from "./primitives/$computed.ts";
 import type { InjectOptions } from "./primitives/$inject.ts";
 import { Module, type WithModule } from "./primitives/$module.ts";
 import { AlsProvider, type StateScope } from "./providers/AlsProvider.ts";
 import { CodecManager } from "./providers/CodecManager.ts";
 import { EventManager } from "./providers/EventManager.ts";
 import { StateManager } from "./providers/StateManager.ts";
-import type { TSchema } from "./providers/TypeProvider.ts";
+import {
+  type Static,
+  type TObject,
+  type TSchema,
+  z,
+} from "./providers/TypeProvider.ts";
 
 /**
  * Core container of the Alepha framework.
@@ -86,8 +92,8 @@ import type { TSchema } from "./providers/TypeProvider.ts";
  * // But you should use $env() primitive to get typed values from the environment.
  * class App {
  *   env = $env(
- *     t.object({
- *  	   MY_VAR: t.text(),
+ *     z.object({
+ *  	   MY_VAR: z.text(),
  *     })
  *   );
  * }
@@ -362,6 +368,7 @@ export class Alepha {
     return this.context.run(callback, data);
   }
 
+  public get<R>(target: Computed<R>, scope?: StateScope): R;
   public get<T extends TAtomObject>(
     target: Atom<T>,
     scope?: StateScope,
@@ -387,6 +394,14 @@ export class Alepha {
     return this;
   }
 
+  /**
+   * Reset an atom back to its declared default value.
+   */
+  public reset<T extends TAtomObject>(target: Atom<T>): this {
+    this.store.reset(target);
+    return this;
+  }
+
   /**
    * True when start() is called.
    *
@@ -921,7 +936,14 @@ export class Alepha {
         return match.instance;
       }
 
-      if (this.started) {
+      // The locked-container guard protects the GLOBAL registry from gaining new
+      // singletons after start. A `scoped` inject targets a per-request registry
+      // (a fresh Map created by `alepha.context.run` per request, resolved at
+      // `registry` above) and is stored only there — it never mutates the global
+      // container. Refusing it after start makes `lifetime: "scoped"` unusable at
+      // the only time it matters (while handling a request), so the guard must
+      // apply only when we are instantiating into the global registry itself.
+      if (this.started && registry === this.registry) {
         const mod = (service as WithModule)[MODULE]?.name;
         throw new ContainerLockedError(
           `Container is locked. No more services can be added. Attempted to inject '${service.name}' from '${parent?.name}'. ${mod ? `Module '${mod}' is not registered ?` : ""}`,
@@ -1011,7 +1033,12 @@ export class Alepha {
       return this.cacheEnv.get(schema) as Static<T>;
     }
 
-    const config = this.codec.validate(schema, this.env) as Record<string, any>;
+    // Env vars are strings on the wire — coerce declared fields to their
+    // schema types (boolean/number) before strict validation.
+    const config = this.codec.validate(
+      schema,
+      coerceObject(schema, this.env),
+    ) as Record<string, any>;
 
     // Sort keys longest-first to prevent substring collisions
     // (e.g. $PORT must not match inside $PORT_NAME).
@@ -1127,13 +1154,25 @@ export class Alepha {
     const env: Record<string, AlephaDumpEnvVariable> = {};
     for (const [schema] of this.cacheEnv.entries()) {
       const ref = schema as any;
-      for (const [key, value] of Object.entries(ref.properties)) {
+      // zod object: `.properties` aliases `.shape`; `required` field names come
+      // from `z.schema.requiredKeys` (zod has no `.required` array — that name
+      // is the `.required()` method). Metadata (description/enum/default) lives
+      // on the unwrapped inner schema, under `.meta()`.
+      const shape = (ref.properties ?? {}) as Record<string, TSchema>;
+      const required = new Set(z.schema.requiredKeys(ref));
+      for (const [key, value] of Object.entries(shape)) {
         const prop = value as any;
+        const inner = z.schema.unwrap(prop) as any;
+        const enumValues = z.schema.isEnum(inner)
+          ? z.schema.enumValues(inner)
+          : undefined;
         env[key] = {
-          description: prop.description,
-          default: prop.default,
-          required: ref.required?.includes(key) ?? undefined,
-          enum: prop.enum ? ([...prop.enum] as Array<string>) : undefined,
+          description: inner?.description ?? prop?.description,
+          default: z.schema.getDefault(prop) as string | undefined,
+          required: required.has(key) ? true : undefined,
+          enum: enumValues?.length
+            ? ([...enumValues] as Array<string>)
+            : undefined,
         };
       }
     }
@@ -1347,8 +1386,8 @@ export interface State {
    *   db = $inject(DatabaseProvider);
    *   alepha = $inject(Alepha);
    *   env = $env(
-   *     t.object({
-   *       MIGRATE: t.optional(t.boolean()),
+   *     z.object({
+   *       MIGRATE: z.boolean().optional(),
    *     }),
    *   );
    *
@@ -1461,4 +1500,14 @@ export interface Hooks {
      */
     prevValue: any;
   };
+
+  /**
+   * Triggered the first time an atom is registered in the state manager.
+   */
+  "state:register": {
+    /**
+     * The atom that was registered.
+     */
+    atom: Atom<any, any>;
+  };
 }

package/src/core/__tests__/$atom.spec.ts

@@ -1,14 +1,15 @@
 import { Alepha, type State } from "alepha";
 import { describe, expect, it } from "vitest";
+import { AlephaError } from "../errors/AlephaError.ts";
 import { $atom } from "../primitives/$atom.ts";
 import { $state } from "../primitives/$state.ts";
-import { t } from "../providers/TypeProvider.ts";
+import { z } from "../providers/TypeProvider.ts";
 
 describe("$atom", () => {
   const count = $atom({
     name: "count",
-    schema: t.object({
-      value: t.number(),
+    schema: z.object({
+      value: z.number(),
     }),
     default: {
       value: 0,
@@ -41,3 +42,51 @@ describe("$atom", () => {
     expect(app.count.value).toBe(23);
   });
 });
+
+describe("$atom: serverOnly + persist is a contradiction", () => {
+  it("throws AlephaError when combined with persist: cookie", () => {
+    expect(() =>
+      $atom({
+        name: "test.extras.serverOnlyCookie",
+        schema: z.object({ token: z.string() }),
+        default: { token: "" },
+        serverOnly: true,
+        persist: "cookie",
+      }),
+    ).toThrow(AlephaError);
+  });
+
+  it("throws AlephaError when combined with persist: localStorage", () => {
+    expect(() =>
+      $atom({
+        name: "test.extras.serverOnlyLocalStorage",
+        schema: z.object({ token: z.string() }),
+        default: { token: "" },
+        serverOnly: true,
+        persist: "localStorage",
+      }),
+    ).toThrow(AlephaError);
+  });
+
+  it("does not throw when only serverOnly is set", () => {
+    expect(() =>
+      $atom({
+        name: "test.extras.serverOnlyAlone",
+        schema: z.object({ token: z.string() }),
+        default: { token: "" },
+        serverOnly: true,
+      }),
+    ).not.toThrow();
+  });
+
+  it("does not throw when only persist is set", () => {
+    expect(() =>
+      $atom({
+        name: "test.extras.persistAlone",
+        schema: z.object({ token: z.string() }),
+        default: { token: "" },
+        persist: "cookie",
+      }),
+    ).not.toThrow();
+  });
+});

package/src/core/__tests__/$computed.spec.ts

@@ -0,0 +1,129 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { Alepha } from "../Alepha.ts";
+import { AlephaError } from "../errors/AlephaError.ts";
+import { $atom } from "../primitives/$atom.ts";
+import { $computed } from "../primitives/$computed.ts";
+import { AlsProvider } from "../providers/AlsProvider.ts";
+import { z } from "../providers/TypeProvider.ts";
+
+describe("$computed", () => {
+  const cart = $atom({
+    name: "test.computed.cart",
+    schema: z.object({
+      items: z.array(z.object({ price: z.number(), qty: z.number() })),
+    }),
+    default: { items: [] },
+  });
+
+  const total = $computed({
+    name: "test.computed.total",
+    deps: [cart],
+    get: (c) => c.items.reduce((sum, item) => sum + item.price * item.qty, 0),
+  });
+
+  const doubled = $computed({
+    name: "test.computed.doubled",
+    deps: [total],
+    get: (t) => t * 2,
+  });
+
+  it("computes from dependency defaults", () => {
+    const alepha = Alepha.create();
+    expect(alepha.store.get(total)).toBe(0);
+  });
+
+  it("reflects dependency mutations", () => {
+    const alepha = Alepha.create();
+    alepha.store.set(cart, { items: [{ price: 10, qty: 2 }] });
+    expect(alepha.store.get(total)).toBe(20);
+  });
+
+  it("supports computed-on-computed", () => {
+    const alepha = Alepha.create();
+    alepha.store.set(cart, { items: [{ price: 5, qty: 1 }] });
+    expect(alepha.store.get(doubled)).toBe(10);
+  });
+
+  it("lists transitive dependency keys", () => {
+    expect(doubled.keys()).toEqual(["test.computed.cart"]);
+  });
+
+  it("cannot be set", () => {
+    const alepha = Alepha.create();
+    expect(() => alepha.store.set(total as any, 5)).toThrow(AlephaError);
+  });
+
+  it("is never exported for hydration", () => {
+    const alepha = Alepha.create();
+    alepha.store.get(total);
+    expect(Object.keys(alepha.store.exportAtoms())).not.toContain(
+      "test.computed.total",
+    );
+  });
+
+  it("is readable through alepha.get", () => {
+    const alepha = Alepha.create();
+    alepha.store.set(cart, { items: [{ price: 3, qty: 3 }] });
+    expect(alepha.get(total)).toBe(9);
+  });
+
+  // "Keeps ALS fork-scoped deps correct for free" is the stated design
+  // rationale for $computed's no-cache decision (see this file's brief and
+  // $computed.ts's JSDoc) — exercise it directly instead of trusting code
+  // inspection. `AlsProvider.create` defaults to a no-op (`fork()` becomes a
+  // plain function call); swap in a real `AsyncLocalStorage` for this block
+  // only, mirroring `fork.spec.ts`.
+  describe("inside a fork", () => {
+    const originalAlsCreate = AlsProvider.create;
+
+    beforeAll(() => {
+      AlsProvider.create = () => new AsyncLocalStorage();
+    });
+
+    afterAll(() => {
+      AlsProvider.create = originalAlsCreate;
+    });
+
+    it("resolves a dependency from the fork's own value, not the app store's", () => {
+      const alepha = new Alepha();
+      alepha.store.set(cart, { items: [{ price: 10, qty: 1 }] });
+      expect(alepha.store.get(total)).toBe(10);
+
+      alepha.fork(() => {
+        alepha.store.set(cart, { items: [{ price: 2, qty: 3 }] });
+        expect(alepha.store.get(total)).toBe(6);
+      });
+
+      // The fork-scoped mutation must not leak back into the app-level store.
+      expect(alepha.store.get(total)).toBe(10);
+    });
+  });
+
+  describe("circular dependencies", () => {
+    it("throws AlephaError instead of overflowing the stack", () => {
+      const cycleA = $computed({
+        name: "test.computed.cycleA",
+        deps: [],
+        get: () => 0,
+      });
+      const cycleB = $computed({
+        name: "test.computed.cycleB",
+        deps: [cycleA],
+        get: (v: number) => v + 1,
+      });
+
+      // `deps` is `readonly` only at the type level — nothing stops a
+      // caller from mutating the underlying array at runtime and building a
+      // genuine cycle. That's exactly what this test does to exercise the
+      // guard; there is no supported public API to construct a cycle any
+      // other way.
+      (cycleA.options.deps as unknown[]).push(cycleB);
+
+      expect(() => cycleA.keys()).toThrow(AlephaError);
+
+      const alepha = Alepha.create();
+      expect(() => alepha.store.get(cycleA)).toThrow(AlephaError);
+    });
+  });
+});

package/src/core/__tests__/$env.spec.ts

@@ -1,12 +1,12 @@
-import { $env, $inject, Alepha, AlephaError, TypeBoxError, t } from "alepha";
+import { $env, $inject, Alepha, AlephaError, TypeBoxError, z } from "alepha";
 import { describe, expect, it } from "vitest";
 
 describe("$env", () => {
   it("should parse env variables from Alepha config", () => {
     class App {
       env = $env(
-        t.object({
-          PORT: t.text(),
+        z.object({
+          PORT: z.text(),
         }),
       );
     }
@@ -18,8 +18,8 @@ describe("$env", () => {
   it("should apply default values when var is missing", () => {
     class App {
       env = $env(
-        t.object({
-          HOST: t.text({ default: "localhost" }),
+        z.object({
+          HOST: z.text({ default: "localhost" }),
         }),
       );
     }
@@ -31,9 +31,9 @@ describe("$env", () => {
   it("should interpolate env references", () => {
     class App {
       env = $env(
-        t.object({
-          BASE: t.text(),
-          URL: t.text({ default: "$BASE/api" }),
+        z.object({
+          BASE: z.text(),
+          URL: z.text({ default: "$BASE/api" }),
         }),
       );
     }
@@ -47,8 +47,8 @@ describe("$env", () => {
   it("should throw TypeBoxError when required var is missing", () => {
     class App {
       env = $env(
-        t.object({
-          REQUIRED: t.text(),
+        z.object({
+          REQUIRED: z.text(),
         }),
       );
     }
@@ -58,14 +58,14 @@ describe("$env", () => {
 
   it("should throw AlephaError for non-TObject schema", () => {
     class App {
-      env = $env(t.text() as any);
+      env = $env(z.text() as any);
     }
 
     expect(() => Alepha.create().inject(App)).toThrow(AlephaError);
   });
 
   it("should share parsed env across services", () => {
-    const schema = t.object({ KEY: t.text() });
+    const schema = z.object({ KEY: z.text() });
 
     class A {
       env = $env(schema);
@@ -113,7 +113,7 @@ describe("$env", () => {
 
     it("is resolvable through $env after merge", () => {
       class App {
-        env = $env(t.object({ PUBLIC_URL: t.text({ default: "" }) }));
+        env = $env(z.object({ PUBLIC_URL: z.text({ default: "" }) }));
       }
 
       const alepha = Alepha.create();

package/src/core/__tests__/$inject.spec.ts

@@ -6,7 +6,7 @@ import {
   CircularDependencyError,
   type Service,
   TypeBoxError,
-  t,
+  z,
 } from "alepha";
 import { describe, expect, it } from "vitest";
 import { MissingContextError } from "../errors/MissingContextError.ts";
@@ -53,9 +53,9 @@ describe("$env", () => {
   it("should inject environment variables correctly", () => {
     class A {
       env = $env(
-        t.object({
-          N1: t.text(),
-          N2: t.text({ default: "$N1" }),
+        z.object({
+          N1: z.text(),
+          N2: z.text({ default: "$N1" }),
         }),
       );
     }

package/src/core/__tests__/$module.spec.ts

@@ -61,7 +61,7 @@ describe("$module", () => {
         module: "alepha.core",
       },
       SchemaValidator: {
-        from: ["CodecManager"],
+        from: ["StateManager", "CodecManager"],
         module: "alepha.core",
       },
     });

package/src/core/__tests__/Alepha-graph.spec.ts

@@ -89,7 +89,7 @@ describe("Alepha#graph", () => {
         module: "alepha.core",
       },
       SchemaValidator: {
-        from: ["CodecManager"],
+        from: ["StateManager", "CodecManager"],
         module: "alepha.core",
       },
     });

package/src/core/__tests__/Alepha-parseEnv.spec.ts

@@ -1,12 +1,12 @@
-import { Alepha, t } from "alepha";
+import { Alepha, z } from "alepha";
 import { describe, expect, it } from "vitest";
 
 describe("Alepha#parseEnv", () => {
   it("should substitute $KEY placeholders in string values", async () => {
-    const schema = t.object({
-      HOST: t.optional(t.text()),
-      PORT: t.optional(t.text()),
-      BASE_URL: t.optional(t.text()),
+    const schema = z.object({
+      HOST: z.text().optional(),
+      PORT: z.text().optional(),
+      BASE_URL: z.text().optional(),
     });
 
     const alepha = Alepha.create({
@@ -22,9 +22,9 @@ describe("Alepha#parseEnv", () => {
   });
 
   it("should handle keys with regex-special characters", async () => {
-    const schema = t.object({
-      "API.URL": t.optional(t.text()),
-      RESULT: t.optional(t.text()),
+    const schema = z.object({
+      "API.URL": z.text().optional(),
+      RESULT: z.text().optional(),
     });
 
     const alepha = Alepha.create({
@@ -39,10 +39,10 @@ describe("Alepha#parseEnv", () => {
   });
 
   it("should coerce non-string replacement sources", async () => {
-    const schema = t.object({
-      PORT: t.optional(t.text()),
-      DEBUG: t.optional(t.text()),
-      URL: t.optional(t.text()),
+    const schema = z.object({
+      PORT: z.text().optional(),
+      DEBUG: z.text().optional(),
+      URL: z.text().optional(),
     });
 
     const alepha = Alepha.create({
@@ -58,8 +58,8 @@ describe("Alepha#parseEnv", () => {
   });
 
   it("should leave unresolved placeholders as-is", async () => {
-    const schema = t.object({
-      URL: t.optional(t.text()),
+    const schema = z.object({
+      URL: z.text().optional(),
     });
 
     const alepha = Alepha.create({
@@ -71,9 +71,9 @@ describe("Alepha#parseEnv", () => {
   });
 
   it("should match env keys case-sensitively", async () => {
-    const schema = t.object({
-      HOST: t.optional(t.text()),
-      URL: t.optional(t.text()),
+    const schema = z.object({
+      HOST: z.text().optional(),
+      URL: z.text().optional(),
     });
 
     const alepha = Alepha.create({
@@ -85,10 +85,10 @@ describe("Alepha#parseEnv", () => {
   });
 
   it("should resolve transitive $KEY references", async () => {
-    const schema = t.object({
-      A: t.optional(t.text()),
-      B: t.optional(t.text()),
-      C: t.optional(t.text()),
+    const schema = z.object({
+      A: z.text().optional(),
+      B: z.text().optional(),
+      C: z.text().optional(),
     });
 
     const alepha = Alepha.create({
@@ -105,10 +105,10 @@ describe("Alepha#parseEnv", () => {
   });
 
   it("should not replace substring keys when a longer key matches", async () => {
-    const schema = t.object({
-      PORT: t.optional(t.text()),
-      PORT_NAME: t.optional(t.text()),
-      URL: t.optional(t.text()),
+    const schema = z.object({
+      PORT: z.text().optional(),
+      PORT_NAME: z.text().optional(),
+      URL: z.text().optional(),
     });
 
     const alepha = Alepha.create({
@@ -124,11 +124,11 @@ describe("Alepha#parseEnv", () => {
   });
 
   it("should handle overlapping key prefixes correctly", async () => {
-    const schema = t.object({
-      A: t.optional(t.text()),
-      AB: t.optional(t.text()),
-      ABC: t.optional(t.text()),
-      RESULT: t.optional(t.text()),
+    const schema = z.object({
+      A: z.text().optional(),
+      AB: z.text().optional(),
+      ABC: z.text().optional(),
+      RESULT: z.text().optional(),
     });
 
     const alepha = Alepha.create({
@@ -145,8 +145,8 @@ describe("Alepha#parseEnv", () => {
   });
 
   it("should return cached result for same schema", async () => {
-    const schema = t.object({
-      FOO: t.optional(t.text()),
+    const schema = z.object({
+      FOO: z.text().optional(),
     });
 
     const alepha = Alepha.create({

package/src/core/__tests__/Alepha-start.spec.ts

@@ -1,4 +1,4 @@
-import { $env, $hook, $inject, Alepha, ContainerLockedError, t } from "alepha";
+import { $env, $hook, $inject, Alepha, ContainerLockedError, z } from "alepha";
 import { describe, expect, it } from "vitest";
 
 describe("Alepha#start", () => {
@@ -19,8 +19,8 @@ describe("Alepha#start", () => {
     class A {
       a = "a";
       e = $env(
-        t.object({
-          HELLO: t.text(),
+        z.object({
+          HELLO: z.text(),
         }),
       );
     }