experimental-a2 0.0.0

package/dist/contract-DL8btVd9.d.ts

@@ -0,0 +1,161 @@
+//#region src/standard-schema.d.ts
+/**
+ * The Standard Schema interface, vendored per the spec's guidance
+ * (https://standardschema.dev — the interface is designed to be copied
+ * into libraries rather than depended on). Types only; nothing here
+ * exists at runtime.
+ */
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  export interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The result interface of the validate function. */
+  export type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  export interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** The non-existent issues. */
+    readonly issues?: undefined;
+  }
+  /** The result interface if validation fails. */
+  export interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /** The issue interface of the failure output. */
+  export interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  export interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard Schema types interface. */
+  export interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Schema. */
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+  /** Infers the output type of a Standard Schema. */
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+//#endregion
+//#region src/reducer.d.ts
+/**
+ * A pure fold over a session's events — `(state, event) => state` —
+ * derived from a contract via `contract.reducer(options).fold(fn)`.
+ *
+ * The name is the reducer's identity. Cached folds (server snapshots,
+ * the browser cache) are keyed by it, which makes it the invalidation
+ * knob too: changed the fold's logic? Change the name. Snapshots under
+ * the old name are ignored and the next read refolds from raw events.
+ * See docs/concepts/04-state.mdx.
+ */
+type Reducer<D extends EventDefs = EventDefs, S = unknown> = {
+  /** Identity and cache key. Rename when the fold's logic changes. */
+  readonly name: string;
+  /** The contract's vocabulary — types every event in the fold. */
+  readonly events: Readonly<D>;
+  readonly fold: (state: S, event: ContractEvent<D>) => S;
+  readonly initialState: S;
+  /**
+   * When present: `initialState` was validated against it at
+   * definition, and any cached fold a2 rehydrates (server snapshots,
+   * the browser cache) is checked against it — failing snapshots are
+   * discarded and refolded, catching shape drift a stale name can't.
+   */
+  readonly stateSchema: StandardSchemaV1<unknown, S> | undefined;
+};
+/** The second step of `contract.reducer` — see the method's doc. */
+type ReducerBuilder<D extends EventDefs, S> = {
+  fold(fold: (state: S, event: ContractEvent<D>) => S): Reducer<D, S>;
+};
+//#endregion
+//#region src/contract.d.ts
+/** The event vocabulary shape: event name → payload schema. */
+type EventDefs = Record<string, StandardSchemaV1>;
+/** One event of a contract, narrowed to type `K`. */
+type ContractEvent<D extends EventDefs, K extends keyof D & string = keyof D & string> = { [T in keyof D & string]: {
+  id: string;
+  type: T;
+  payload: StandardSchemaV1.InferOutput<D[T]>;
+  index: number;
+  sessionId: string;
+  createdAt: Date;
+}; }[K];
+/** Input to `append`/`push`, typed against the contract's schemas. */
+type AppendInput<D extends EventDefs> = { [T in keyof D & string]: {
+  type: T;
+  payload: StandardSchemaV1.InferInput<D[T]>;
+  id?: string;
+}; }[keyof D & string];
+type ReducerOptions<Seed, S> = {
+  /**
+   * Identity and snapshot cache key. Rename it when the fold's logic
+   * changes — snapshots under the old name are ignored and refolded.
+   */
+  name: string;
+  /**
+   * The seed the fold starts from. With a `stateSchema`, it's typed as
+   * the schema's *input*: validated at definition, and the validated
+   * output (defaults applied) is what the fold actually starts from.
+   */
+  initialState: Seed;
+  /**
+   * Optional: declares the state's shape (the fold's state type becomes
+   * the schema's output) and guards cached folds — server snapshots and
+   * the browser cache reject mismatching shapes and refold.
+   */
+  stateSchema?: StandardSchemaV1<Seed, S>;
+};
+type Contract<D extends EventDefs = EventDefs> = {
+  /** Identity — prefixes storage keys and queue messages. */
+  readonly name: string;
+  /** The vocabulary. */
+  readonly events: Readonly<D>;
+  /**
+   * Derive a view from this contract. The reducer's `name` is its
+   * identity and snapshot cache key: rename it when the fold's logic
+   * changes. Two steps by design: this call fixes the state and event
+   * types, so `.fold()` receives fully concrete types — literal unions
+   * in your state survive, with zero annotations. (A single call can't
+   * do this: TypeScript never contextually types the returns of a
+   * context-sensitive argument against generics inferred in the same
+   * call.)
+   */
+  reducer<Seed, S = Seed>(options: ReducerOptions<Seed, S>): ReducerBuilder<D, S>;
+};
+/**
+ * Define a contract: a name plus the events it understands. Validators
+ * must be synchronous — async ones are rejected here, at definition
+ * time. The result is a plain, importable, isomorphic value.
+ */
+declare function contract<D extends EventDefs>(options: {
+  /** Identity — prefixes storage keys and queue messages. */
+  name: string;
+  /** The vocabulary: event name → payload schema (Standard Schema). */
+  events: D;
+}): Contract<D>;
+//#endregion
+export { ReducerOptions as a, ReducerBuilder as c, EventDefs as i, StandardSchemaV1 as l, Contract as n, contract as o, ContractEvent as r, Reducer as s, AppendInput as t };

package/dist/devtools-server.browser.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/devtools-server.browser.js

@@ -0,0 +1,4 @@
+//#region src/devtools-server.browser.ts
+/** a2/devtools/server owns log access and is server-only. */
+throw new Error("a2/devtools/server is server-only — mount its handler in a server route and open that URL in the browser.");
+//#endregion

package/dist/devtools-server.d.ts

@@ -0,0 +1,22 @@
+//#region src/devtools-server.d.ts
+type DevtoolsServer = {
+  readonly contract: {
+    readonly name: string;
+  };
+};
+type DevtoolsAuthorization = (request: Request) => boolean | Response | Promise<boolean | Response>;
+type DevtoolsOptions = {
+  servers: readonly DevtoolsServer[];
+  /**
+   * Application-owned access control. Returning a Response short-circuits
+   * the request. Without this option, devtools is available outside
+   * production and returns 404 in production.
+   */
+  authorize?: DevtoolsAuthorization;
+};
+type Devtools = {
+  handler(): (request: Request) => Promise<Response>;
+};
+declare function createDevtools(options: DevtoolsOptions): Devtools;
+//#endregion
+export { Devtools, DevtoolsAuthorization, DevtoolsOptions, DevtoolsServer, createDevtools };