zerodrift 1.0.4 → 1.1.0

package/README.md

@@ -157,15 +157,17 @@ Both authoring paths compile to the same registry, so schema entities and decora
 
 ## React quick start
 
-Wrap your app in `<SyncProvider>` once. Import your model file as a side effect so decorators run before bootstrap.
+Wrap your app in `<SyncProvider>` once. For the decorator path, import your model file as a side effect so decorators run before bootstrap; for the schema-first path, pass `schema={schema}` and the provider registers entities before fetching.
 
 ```tsx
 import { SyncProvider } from "zerodrift/react";
-import "./models";
+import { schema } from "./schema";   // schema-first
+// import "./models";                  // or: decorator path — side-effect import
 
 export default function Providers({ children }) {
   return (
     <SyncProvider
+      schema={schema}
       config={{
         workspaceId: "workspace-123",
         transport: {
@@ -194,6 +196,16 @@ export default function Providers({ children }) {
 }
 ```
 
+In schema-first children, pull the typed store with `useStore<typeof schema>()` (add `typeof extensions` as the second generic if you also passed extensions):
+
+```tsx
+import { useStore } from "zerodrift/react";
+import { schema } from "./schema";
+
+const store = useStore<typeof schema>();
+const { data: issue } = useRecord(store.issue, issueId);
+```
+
 Common reads and writes. The read hooks take a **handle** — a model class
 (decorator path) or a `store.<entity>` namespace (schema path) — and infer
 the record type from it. Every result has the same shape:
@@ -227,7 +239,7 @@ const { data: teams } = useRecords(store.team);
 const { data: teamIssues } = useRecordsByIndex(store.issue, "teamId", teamId);
 ```
 
-See [agent-docs/08-react-integration.md](agent-docs/08-react-integration.md) for hook return shapes, context-driven id generation, Storybook seeding, and testing patterns.
+See [agent-docs/08-react-integration.md](agent-docs/08-react-integration.md) for hook return shapes, context-driven id generation, Storybook seeding, and testing patterns. For the full `transport` field list (`bootstrapSyncGroups`, `modelStreams`, `sseClientFactory`, `syncTransform`, …) see [TransportConfig reference](agent-docs/07-realtime-sync.md#transportconfig-reference).
 
 ## Headless usage
 

package/dist/core/BaseSSEConnection.d.ts

@@ -8,19 +8,25 @@ export interface SSEClient {
 }
 export type SSEClientFactory = (url: string) => SSEClient;
 export type SSEErrorReporter = (err: Error, context: EngineErrorContext) => void;
+/** Either a fixed URL or a thunk re-evaluated on every (re)connect. */
+export type SSEEndpoint = string | (() => string);
 export declare const createBrowserSSEFactory: (init?: EventSourceInit) => SSEClientFactory;
 export declare abstract class BaseSSEConnection {
-    protected url: string;
+    protected url: SSEEndpoint;
     private sseClientFactory;
     private reportError?;
     private eventSource;
     private reconnectTimer;
     private stopped;
-    constructor(url: string, sseClientFactory?: SSEClientFactory, reportError?: SSEErrorReporter | undefined);
+    constructor(url: SSEEndpoint, sseClientFactory?: SSEClientFactory, reportError?: SSEErrorReporter | undefined);
     connect(): void;
     disconnect(): void;
     reconnect(): void;
     get isConnected(): boolean;
+    /** Resolve the endpoint to a concrete string. Subclasses building dynamic
+     * URLs (e.g. appending query params) must read through this instead of
+     * `this.url` directly so a thunk endpoint is re-evaluated on every connect. */
+    protected resolveUrl(): string;
     protected buildUrl(): string;
     protected abstract onMessage(data: string): void;
     protected onReconnect(): void;

package/dist/core/BaseSSEConnection.js

@@ -36,8 +36,14 @@ export class BaseSSEConnection {
     get isConnected() {
         return this.eventSource != null;
     }
+    /** Resolve the endpoint to a concrete string. Subclasses building dynamic
+     * URLs (e.g. appending query params) must read through this instead of
+     * `this.url` directly so a thunk endpoint is re-evaluated on every connect. */
+    resolveUrl() {
+        return typeof this.url === "function" ? this.url() : this.url;
+    }
     buildUrl() {
-        return this.url;
+        return this.resolveUrl();
     }
     onReconnect() { }
     onOpen() { }
@@ -51,7 +57,21 @@ export class BaseSSEConnection {
             this.eventSource = null;
             this.onClose();
         }
-        const url = this.buildUrl();
+        // buildUrl() can throw when the endpoint is a thunk (e.g. cursor read
+        // crashes). Catch + schedule a reconnect so a transient failure doesn't
+        // permanently kill the stream.
+        let url;
+        try {
+            url = this.buildUrl();
+        }
+        catch (err) {
+            this.reportError?.(toError(err), {
+                kind: "sseConstruction",
+                url: "<endpoint-thunk-threw>",
+            });
+            this.scheduleReconnect();
+            return;
+        }
         try {
             this.eventSource = this.sseClientFactory(url);
             this.eventSource.onmessage = (e) => {

package/dist/core/Database.d.ts

@@ -201,7 +201,8 @@ export interface StorageAdapter {
     close(): Promise<void>;
     /**
      * Close the connection AND permanently delete all persisted data.
-     * Use for explicit logout / factory-reset flows — NOT for routine teardown.
+     * Called by StoreManager.destroy() for explicit logout / factory-reset
+     * flows — NOT for routine teardown.
      */
     destroy(): Promise<void>;
     get isConnected(): boolean;

package/dist/core/ModelStream.d.ts

@@ -5,7 +5,7 @@
  */
 import type { StorageAdapter } from "./Database.js";
 import { ObjectPool } from "./ObjectPool.js";
-import { BaseSSEConnection, type SSEClientFactory, type SSEErrorReporter } from "./BaseSSEConnection.js";
+import { BaseSSEConnection, type SSEClientFactory, type SSEEndpoint, type SSEErrorReporter } from "./BaseSSEConnection.js";
 export interface ModelUpdate {
     modelName: string;
     modelId: string;
@@ -23,7 +23,7 @@ export declare class ModelStream extends BaseSSEConnection {
     private transform?;
     private updateQueue;
     private processing;
-    constructor(url: string, database: StorageAdapter, pool: ObjectPool, onStatusChange?: ((connected: boolean) => void) | undefined, sseClientFactory?: SSEClientFactory, transform?: ModelStreamMessageTransform | undefined, reportError?: SSEErrorReporter);
+    constructor(url: SSEEndpoint, database: StorageAdapter, pool: ObjectPool, onStatusChange?: ((connected: boolean) => void) | undefined, sseClientFactory?: SSEClientFactory, transform?: ModelStreamMessageTransform | undefined, reportError?: SSEErrorReporter);
     disconnect(): void;
     protected onOpen(): void;
     protected onClose(): void;

package/dist/core/StoreManager.d.ts

@@ -21,7 +21,7 @@
 import { ObjectPool } from "./ObjectPool.js";
 import { BootstrapType, type StorageAdapter, type DatabaseMeta, type PartialIndexEntry } from "./Database.js";
 import { TransactionQueue, type TransactionSender, type UndoableActionHandlers } from "./TransactionQueue.js";
-import { type DeltaPacket, type SSEClientFactory, type SyncMessageTransform } from "./SyncConnection.js";
+import { type DeltaPacket, type SSEClientFactory, type SSEEndpoint, type SyncMessageTransform } from "./SyncConnection.js";
 import { type ModelStreamMessageTransform } from "./ModelStream.js";
 import { type IndexBatchFetcher } from "./BatchModelLoader.js";
 import { BaseModel } from "./BaseModel.js";
@@ -68,7 +68,7 @@ export interface BootstrapFetcherOptions extends FetcherContext {
 }
 export type BootstrapFetcher = (type: BootstrapType.Full | BootstrapType.Partial, options?: BootstrapFetcherOptions) => Promise<BootstrapResponse>;
 export interface ModelStreamConfig {
-    url: string;
+    url: SSEEndpoint;
     onStatusChange?: (connected: boolean) => void;
     /**
      * Use when the backend sends a different envelope than the engine's
@@ -107,7 +107,10 @@ export type OnDemandConfig = {
 export interface TransportConfig {
     bootstrapFetcher: BootstrapFetcher;
     transactionSender?: TransactionSender;
-    syncUrl?: string;
+    /** SSE endpoint for live deltas — a static string, or a thunk evaluated
+     * on every (re)connect (so callers can fold in cursors from localStorage,
+     * auth tokens in the path, etc., without rebuilding the engine). */
+    syncUrl?: SSEEndpoint;
     /**
      * Optional async hook that returns the user's sync-group memberships
      * before any bootstrap fetch runs. The returned groups are append-only
@@ -829,7 +832,15 @@ export declare class StoreManager<TContext = unknown> {
      * cleared here because the schema-mismatch path keeps coverage entries;
      * the `fullyLoadedModels` mirror stays consistent with that. */
     private resetPoolState;
+    /** Routine cleanup (e.g. React unmount): stop sync, clear the object pool,
+     * and `close()` the persistence layer — persisted data is preserved so the
+     * next load can do a fast partial/local bootstrap. Not a logout. */
     teardown(): Promise<void>;
+    /** Logout / account switch: stop sync, clear the object pool, and `destroy()`
+     * the persistence layer — permanently wiping its data, whether persistence is
+     * IndexedDB or in-memory. Unlike {@link teardown}, nothing survives. */
+    destroy(): Promise<void>;
+    private shutdown;
     /** Debounced reconnect for SSE when `loadedModels` mutates. A burst of
      * transitions in the same tick (or across awaited writes in the same
      * async chain) coalesces into a single reconnect. setTimeout — not

package/dist/core/StoreManager.js

@@ -1980,7 +1980,19 @@ export class StoreManager {
         this.inflightFullLoads.clear();
         this.seededSyncGroups = [];
     }
+    /** Routine cleanup (e.g. React unmount): stop sync, clear the object pool,
+     * and `close()` the persistence layer — persisted data is preserved so the
+     * next load can do a fast partial/local bootstrap. Not a logout. */
     async teardown() {
+        await this.shutdown(false);
+    }
+    /** Logout / account switch: stop sync, clear the object pool, and `destroy()`
+     * the persistence layer — permanently wiping its data, whether persistence is
+     * IndexedDB or in-memory. Unlike {@link teardown}, nothing survives. */
+    async destroy() {
+        await this.shutdown(true);
+    }
+    async shutdown(destroyData) {
         this.stopped = true;
         BaseModel.storeManager = null;
         this.loadedModelsUnsub?.();
@@ -1998,7 +2010,7 @@ export class StoreManager {
         this.transactionQueue.destroy();
         this.indexBatchLoader?.dispose();
         this.indexBatchLoader = null;
-        await this.database.close();
+        await (destroyData ? this.database.destroy() : this.database.close());
         this.objectPool.clear();
         this.stores.clear();
         this.partialIndexCoverage.clear();

package/dist/core/SyncConnection.d.ts

@@ -24,8 +24,8 @@
 import type { StorageAdapter } from "./Database.js";
 import { ObjectPool } from "./ObjectPool.js";
 import { TransactionQueue } from "./TransactionQueue.js";
-import { BaseSSEConnection, type SSEClientFactory, type SSEErrorReporter } from "./BaseSSEConnection.js";
-export { type SSEClient, type SSEClientFactory, type SSEErrorReporter, createBrowserSSEFactory, } from "./BaseSSEConnection.js";
+import { BaseSSEConnection, type SSEClientFactory, type SSEEndpoint, type SSEErrorReporter } from "./BaseSSEConnection.js";
+export { type SSEClient, type SSEClientFactory, type SSEEndpoint, type SSEErrorReporter, createBrowserSSEFactory, } from "./BaseSSEConnection.js";
 /**
  * Encode each element then comma-join — the right shape for a list-of-
  * strings inside a URL query parameter or a stable cache key. Commas
@@ -92,7 +92,7 @@ export declare class SyncConnection extends BaseSSEConnection {
      * gate, which doesn't see `getOrLoadAll`'s sentinel coverage. */
     private isModelFullyLoaded?;
     private recordInflightDelete?;
-    constructor(url: string, database: StorageAdapter, pool: ObjectPool, queue: TransactionQueue, opts?: SyncConnectionOptions);
+    constructor(url: SSEEndpoint, database: StorageAdapter, pool: ObjectPool, queue: TransactionQueue, opts?: SyncConnectionOptions);
     protected buildUrl(): string;
     protected onMessage(data: string): void;
     protected onReconnect(): void;

package/dist/core/SyncConnection.js

@@ -67,11 +67,8 @@ export class SyncConnection extends BaseSSEConnection {
         const meta = this.database.currentMeta;
         const lastSyncId = meta?.lastSyncId ?? 0;
         const syncGroups = encodeCsvList(meta?.subscribedSyncGroups ?? []);
-        // Tell the server which models we're subscribed to (catchup + live
-        // stream; absent → no filter). Union of always-subscribed (Eager +
-        // Ephemeral, see ModelRegistry) with adapter-tracked loadedModels.
-        // Sort for a stable URL — equivalent sets must produce identical URLs
-        // so the engine doesn't churn reconnects when iteration order shifts.
+        // Sort the union — equivalent sets must produce identical URLs so the
+        // engine doesn't churn reconnects when iteration order shifts.
         const subscribed = [
             ...new Set([
                 ...ModelRegistry.alwaysSubscribedModelNames(),
@@ -79,7 +76,11 @@ export class SyncConnection extends BaseSSEConnection {
             ]),
         ].sort();
         const onlyModels = subscribed.length > 0 ? `&onlyModels=${encodeCsvList(subscribed)}` : "";
-        return `${this.url}?lastSyncId=${lastSyncId}&syncGroups=${syncGroups}${onlyModels}`;
+        const base = this.resolveUrl();
+        // Thunk endpoints often already carry query params (tenant, cursor, …);
+        // pick `&` when the base is already in query-string mode.
+        const sep = base.includes("?") ? "&" : "?";
+        return `${base}${sep}lastSyncId=${lastSyncId}&syncGroups=${syncGroups}${onlyModels}`;
     }
     onMessage(data) {
         const raw = JSON.parse(data);

package/dist/core/index.d.ts

@@ -12,5 +12,5 @@ export { StoreManager, RestrictDeleteError } from "./StoreManager.js";
 export type { BootstrapResponse, BootstrapFetcher, BootstrapFetcherOptions, FetcherContext, StoreManagerConfig, TransportConfig, LoadingConfig, PersistenceConfig, HooksConfig, AdvancedConfig, OnDemandConfig, OnDemandFetcher, OnDemandBatchFetcher, ModelStreamConfig, } from "./StoreManager.js";
 export type { UndoableAction } from "./Transaction.js";
 export type { TransactionSender, BatchResponse, UndoableActionHandlers, UndoResult, } from "./TransactionQueue.js";
-export type { SyncAction, DeltaPacket, SyncMessageTransform, } from "./SyncConnection.js";
+export type { SyncAction, DeltaPacket, SSEEndpoint, SyncMessageTransform, } from "./SyncConnection.js";
 export type { ModelUpdate, ModelStreamMessageTransform } from "./ModelStream.js";

package/dist/react/index.d.ts

@@ -11,12 +11,16 @@ import { StoreManager, type StoreManagerConfig } from "../core/StoreManager.js";
 import { BootstrapPhase } from "../core/types.js";
 import { LazyCollectionBase, BackRef } from "../core/LazyCollection.js";
 import type { BaseModel } from "../core/BaseModel.js";
+import { type EntityNamespace, type EntityStore, type RecordWithExtensions } from "../schema/createStore.js";
+import type { ExtensionDescriptor } from "../schema/extend.js";
+import type { EntityKey, IndexedFieldKeys } from "../schema/infer.js";
+import type { SchemaDef } from "../schema/types.js";
 export interface SyncStatus {
     phase: BootstrapPhase;
     detail?: string;
     error?: string;
 }
-export declare function SyncProvider<TContext = unknown>({ config, context, children, fallback, }: {
+export declare function SyncProvider<TContext = unknown, S extends SchemaDef = SchemaDef>({ config, schema, extensions, context, children, fallback, }: {
     config: StoreManagerConfig<TContext>;
     /** Live context forwarded to `StoreManager.setContext` — consumed by
      * `identifierFn` when minting ids for client-side models. Pushed
@@ -25,12 +29,22 @@ export declare function SyncProvider<TContext = unknown>({ config, context, chil
     children: React.ReactNode;
     /** Shown while bootstrap is in progress. */
     fallback?: React.ReactNode;
-}): import("react/jsx-runtime").JSX.Element | null;
+} & ({
+    schema?: undefined;
+    extensions?: undefined;
+} | {
+    /** Schema-first wiring. Read the store back with `useStore<typeof schema>()`. */
+    schema: S;
+    extensions?: readonly ExtensionDescriptor<S>[];
+})): import("react/jsx-runtime").JSX.Element | null;
 export declare function useSyncEngine(): {
     sm: StoreManager<any>;
     status: SyncStatus;
+    store?: EntityStore<any, any>;
 };
 export declare function useBootstrapStatus(): SyncStatus;
+/** Read the schema-first store from context — `useStore<typeof schema>()`. */
+export declare function useStore<S extends SchemaDef, const Exts extends readonly ExtensionDescriptor<S>[] = readonly []>(): EntityStore<S, Exts>;
 /**
  * Uniform async-resource shape for every load-aware hook (`useRecord`,
  * `useRecords`, `useRecordsByIndex`, `useRelation`). `data` is the payload
@@ -56,10 +70,6 @@ export declare function useUndoRedo(): {
 };
 export declare function useRelation<T extends BaseModel = BaseModel>(relation: LazyCollectionBase<T> | null | undefined): AsyncResource<T[]>;
 export declare function useRelation<T extends BaseModel = BaseModel>(relation: BackRef<T> | null | undefined): AsyncResource<T | null>;
-import { type EntityNamespace, type RecordWithExtensions } from "../schema/createStore.js";
-import type { ExtensionDescriptor } from "../schema/extend.js";
-import type { EntityKey, IndexedFieldKeys } from "../schema/infer.js";
-import type { SchemaDef } from "../schema/types.js";
 type AnyNamespace = EntityNamespace<any, any, any>;
 type ModelCtor<T extends BaseModel = BaseModel> = abstract new (...args: any[]) => T;
 type Handle = AnyNamespace | ModelCtor;

package/dist/react/index.js

@@ -12,18 +12,25 @@ import { StoreManager } from "../core/StoreManager.js";
 import { BootstrapPhase } from "../core/types.js";
 import { BackRef } from "../core/LazyCollection.js";
 import { readFk } from "../core/ObjectPool.js";
+import { createStore, entityNamespaceRegistryName, } from "../schema/createStore.js";
 // `<any>` keeps the hooks free of TContext — none of them touch it.
 const SyncContext = createContext(null);
 // ---------------------------------------------------------------------------
 // Provider
 // ---------------------------------------------------------------------------
-export function SyncProvider({ config, context, children, fallback, }) {
+export function SyncProvider({ config, schema, extensions, context, children, fallback, }) {
     const [status, setStatus] = useState({
         phase: BootstrapPhase.Idle,
     });
     const smRef = useRef(null);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const storeRef = useRef(undefined);
     const cfgRef = useRef(config);
     cfgRef.current = config;
+    const schemaRef = useRef(schema);
+    schemaRef.current = schema;
+    const extensionsRef = useRef(extensions);
+    extensionsRef.current = extensions;
     // Detect bfcache restores. When a tab is duplicated (or the user navigates
     // back/forward) the browser may restore the page from its back/forward cache
     // (bfcache). In that case the JS heap is frozen and thawed — React effects do
@@ -60,6 +67,15 @@ export function SyncProvider({ config, context, children, fallback, }) {
         if (contextRef.current !== undefined) {
             sm.setContext(contextRef.current);
         }
+        // createStore registers schema entities into ModelRegistry — must
+        // run before bootstrap() so the first fetch sees them.
+        if (schemaRef.current != null) {
+            storeRef.current = createStore({
+                schema: schemaRef.current,
+                storeManager: sm,
+                extensions: extensionsRef.current,
+            });
+        }
         smRef.current = sm;
         sm.bootstrap().catch((err) => {
             if (active) {
@@ -70,6 +86,7 @@ export function SyncProvider({ config, context, children, fallback, }) {
             active = false;
             sm.teardown();
             smRef.current = null;
+            storeRef.current = undefined;
         };
     }, [cfgRef.current.workspaceId]);
     // Push context updates synchronously so an event handler dispatched in the
@@ -87,7 +104,7 @@ export function SyncProvider({ config, context, children, fallback, }) {
         fallback != null) {
         return _jsx(_Fragment, { children: fallback });
     }
-    return (_jsx(SyncContext.Provider, { value: { sm: smRef.current, status }, children: children }));
+    return (_jsx(SyncContext.Provider, { value: { sm: smRef.current, status, store: storeRef.current }, children: children }));
 }
 // ---------------------------------------------------------------------------
 // Core hook
@@ -102,6 +119,14 @@ export function useSyncEngine() {
 export function useBootstrapStatus() {
     return useSyncEngine().status;
 }
+/** Read the schema-first store from context — `useStore<typeof schema>()`. */
+export function useStore() {
+    const ctx = useSyncEngine();
+    if (ctx.store == null) {
+        throw new Error("useStore() requires <SyncProvider schema={…}>.");
+    }
+    return ctx.store;
+}
 /** Subscribe to a model type's pool changes and read a snapshot synchronously.
  *
  * `getSnapshot` is intentionally NOT stabilized — useSyncExternalStore calls
@@ -328,23 +353,6 @@ function useStableCallback(callback) {
     }, [callback]);
     return stableRef.current;
 }
-// ---------------------------------------------------------------------------
-// Public read hooks — keyed by a "handle"
-//
-// A handle is either a schema namespace (`store.issue`) or a decorator
-// model class (`Issue`). Both resolve to a registry name; the record type
-// is inferred from whichever form was passed, so the same four hooks serve
-// both authoring paths with one vocabulary:
-//
-//   useRecord(handle, id)               → AsyncResource<T | null>
-//   useRecords(handle, ids?)            → AsyncResource<T[]>
-//   useRecordsByIndex(handle, key, v|v[]) → AsyncResource<T[]>
-//   useRelation(record.relation)        → AsyncResource<T[] | T | null>
-//
-// For namespace handles the index key is constrained to the schema's
-// `.indexed()` fields; for class handles it's `string`.
-// ---------------------------------------------------------------------------
-import { entityNamespaceRegistryName, } from "../schema/createStore.js";
 function handleRegistryName(handle) {
     if (typeof handle === "function") {
         // Set by @ClientModel (explicit { name } or ctor.name fallback).

package/dist/schema/index.d.ts

@@ -7,7 +7,7 @@ export { createStore } from "./createStore.js";
 export type { EntityStore, EntityNamespace, RecordWithExtensions, StoreApi, } from "./createStore.js";
 export { extend } from "./extend.js";
 export type { ActionFn, ComputedFn, ExtensionDef, ExtensionDescriptor, ExtensionMap, MergedExtensionMembers, } from "./extend.js";
-export { fromZod, entityFromZod } from "./zod.js";
+export { fromZod, entityFromZod, entitiesFromZod } from "./zod.js";
 export type { EntityFromZodFieldOverride, EntityFromZodOpts } from "./zod.js";
 export type { EntityDef, FieldBuilder, FieldKind, FieldMeta, LinkDef, LinkFromSpec, LinkToSpec, OnDelete, SchemaDef, } from "./types.js";
-export type { EntityKey, IndexedFieldKeys, InferCreateInput, InferEntity, InferUpdateInput, RelationCollection, } from "./infer.js";
+export type { EntityKey, IndexedFieldKeys, InferCreateInput, InferEntity, InferRecord, InferUpdateInput, RelationCollection, } from "./infer.js";

package/dist/schema/index.js

@@ -5,4 +5,4 @@ export { fields as s } from "./builders.js";
 export { compileSchema } from "./compile.js";
 export { createStore } from "./createStore.js";
 export { extend } from "./extend.js";
-export { fromZod, entityFromZod } from "./zod.js";
+export { fromZod, entityFromZod, entitiesFromZod } from "./zod.js";

package/dist/schema/infer.d.ts

@@ -81,6 +81,15 @@ type ReverseCollections<S extends SchemaDef, K extends EntityKey<S>> = {
  * with a one-line helper at the call site if they want.
  */
 export type InferEntity<S extends SchemaDef, K extends EntityKey<S>> = EntityFieldTypes<S, K> & SingularRelations<S, K> & ReverseCollections<S, K>;
+/**
+ * Alias for {@link InferEntity}. Provided so the three record-shape helpers
+ * read uniformly at call sites:
+ *
+ *     type Need       = InferRecord<typeof schema, "need">;
+ *     type NeedCreate = InferCreateInput<typeof schema, "need">;
+ *     type NeedUpdate = InferUpdateInput<typeof schema, "need">;
+ */
+export type InferRecord<S extends SchemaDef, K extends EntityKey<S>> = InferEntity<S, K>;
 /**
  * A create-input field is optional when the runtime can fill it without
  * the caller: id-kind (BaseModel auto-assigns a UUID), defaulted fields,

package/dist/schema/zod.d.ts

@@ -1,5 +1,5 @@
 import type { z } from "zod";
-import type { AnyFieldBuilder, EntityDef, FieldBuilder } from "./types.js";
+import type { AnyFieldBuilder, EntityDef, FieldBuilder, FieldKind, FieldMeta } from "./types.js";
 /**
  * Convert any Zod schema into the equivalent schema-first `FieldBuilder`.
  * Handles the common nullable / optional / default modifiers; anything more
@@ -10,31 +10,111 @@ import type { AnyFieldBuilder, EntityDef, FieldBuilder } from "./types.js";
  * caller to have installed `zod`.
  */
 export declare function fromZod<Z extends z.ZodType>(zSchema: Z): FieldBuilder<z.infer<Z>>;
+/**
+ * Maps Zod's `_zod.def.type` discriminator to a schema `FieldKind`. Mirrors
+ * the runtime `PRIMITIVE_KIND` map; anything not covered collapses to `"json"`,
+ * matching `fromZod`'s fallback.
+ */
+type ZodKindFromTypeName<T> = T extends "string" ? "string" : T extends "number" | "int" ? "number" : T extends "boolean" ? "boolean" : T extends "date" ? "date" : "json";
+/**
+ * Type-level analogue of `fromZod`'s runtime walker: peels off `nullable` /
+ * `optional` / `default` wrappers, stamping each on the accumulator, then
+ * collapses the leaf to a kind via `ZodKindFromTypeName`. The result is
+ * intersected with `FieldMeta` so `IsOptionalCreateField` sees the same
+ * `{kind, optional, default}` flags the runtime produces — keeping
+ * create-input optionality aligned for `.optional()` and `.default(...)`
+ * Zod fields, not just `id`.
+ */
+type ZodToFieldMeta<Z, Accum = Record<never, never>> = Z extends {
+    _zod: {
+        def: {
+            type: "nullable";
+            innerType: infer I;
+        };
+    };
+} ? ZodToFieldMeta<I, Accum & {
+    nullable: true;
+}> : Z extends {
+    _zod: {
+        def: {
+            type: "optional";
+            innerType: infer I;
+        };
+    };
+} ? ZodToFieldMeta<I, Accum & {
+    optional: true;
+}> : Z extends {
+    _zod: {
+        def: {
+            type: "default";
+            innerType: infer I;
+        };
+    };
+} ? ZodToFieldMeta<I, Accum & {
+    default: unknown;
+}> : Z extends {
+    _zod: {
+        def: {
+            type: infer T extends string;
+        };
+    };
+} ? Accum & {
+    kind: ZodKindFromTypeName<T>;
+} : Accum;
+/** Empty meta marker — convention-driven flags (autoIndex) layer on top.
+ * `id` is excluded because the storage layer treats the PK specially and
+ * never materializes a secondary index for it; the empty-string suffix is
+ * excluded so a defaulted/blank config value doesn't index every field. */
+type AutoIndexMeta<K, AI extends string | undefined> = K extends "id" ? Record<never, never> : AI extends "" ? Record<never, never> : AI extends string ? K extends `${string}${AI}` ? {
+    indexed: true;
+} : Record<never, never> : Record<never, never>;
+/**
+ * Auto-derived `FieldBuilder` type for a Zod-object key. The `id` key is
+ * special-cased to carry `{kind: "id"}` (the runtime routes `id` through
+ * `fields.id()` regardless of the Zod-declared id type). Every other key
+ * walks its Zod schema via `ZodToFieldMeta` so PK, optional, and default
+ * flags all flow into the field's create-input optionality the same way.
+ * `AI` is the opts.autoIndex suffix — matching keys pick up `{indexed: true}`.
+ */
+type AutoFieldFromZod<K, ZS, AI extends string | undefined = undefined> = K extends "id" ? FieldBuilder<string, FieldMeta & {
+    kind: "id";
+} & AutoIndexMeta<K, AI>> : ZS extends z.ZodType ? FieldBuilder<z.infer<ZS>, FieldMeta & ZodToFieldMeta<ZS> & AutoIndexMeta<K, AI>> : FieldBuilder<unknown, FieldMeta & {
+    kind: FieldKind;
+}>;
 /**
  * Per-field override for `entityFromZod`. Either a chaining function
  * (modifies the auto-derived `FieldBuilder`) or a full `FieldBuilder`
  * (replaces it — useful for FKs and other shapes Zod can't model).
  */
 export type EntityFromZodFieldOverride<AutoT = unknown> = AnyFieldBuilder | ((auto: FieldBuilder<AutoT>) => AnyFieldBuilder);
-type EntityFromZodFieldOverrides<Z extends z.ZodObject> = {
-    [K in keyof z.infer<Z> & string]?: AnyFieldBuilder | ((auto: FieldBuilder<z.infer<Z>[K]>) => unknown);
+type EntityFromZodFieldOverrides<Z extends z.ZodObject, AI extends string | undefined = undefined> = {
+    [K in keyof Z["shape"] & string]?: AnyFieldBuilder | ((auto: AutoFieldFromZod<K, Z["shape"][K], AI>) => unknown);
+};
+/**
+ * Maps any `opts.fields` key that isn't declared on the Zod object to a
+ * branded error-string type. The intersection with the override map then
+ * forces TS to surface "is not assignable to type \"Error: 'foo' is not a
+ * field…\"" — naming the offender — instead of the bare "not assignable to
+ * type 'never'" the previous `Record<…, never>` form produced.
+ */
+type NoExtraZodFieldKeys<Z extends z.ZodObject, F> = {
+    [K in keyof F as K extends keyof Z["shape"] ? never : K]: `Error: '${K & string}' is not a field declared on the Zod object passed to entityFromZod`;
 };
-type NoExtraZodFieldKeys<Z extends z.ZodObject, F> = Record<Exclude<keyof F, keyof z.infer<Z> & string>, never>;
 /**
  * Resolve the field type contributed by an override entry. Functions are
  * unwrapped via their inferred return type so chained modifiers like
  * `.indexed()` carry their narrowed `M` into the entity's inferred fields;
  * direct `FieldBuilder` overrides are used as-is. When no override is
- * provided the auto-derived `FieldBuilder<AutoT>` from Zod stands.
+ * provided the auto-derived `Auto` field stands.
  */
-type FieldFromOverride<O, AutoT> = O extends (...args: never[]) => infer R ? R extends FieldBuilder<infer RT, infer RM> ? [unknown] extends [RT] ? FieldBuilder<AutoT, RM> : R : FieldBuilder<AutoT> : O extends AnyFieldBuilder ? O : FieldBuilder<AutoT>;
+type FieldFromOverride<O, Auto> = O extends (...args: never[]) => infer R ? R extends FieldBuilder<infer RT, infer RM> ? [unknown] extends [RT] ? Auto extends FieldBuilder<infer AT, FieldMeta> ? FieldBuilder<AT, RM> : never : R : Auto : O extends AnyFieldBuilder ? O : Auto;
 /**
  * Per-key merge of the Zod-inferred fields with `opts.fields` overrides.
  * Override metadata (`.indexed()`, refId target, …) propagates into the
  * entity's TS type so downstream helpers like `IndexedFieldKeys` see them.
  */
-type MergedFieldsFromZodObject<Z extends z.ZodObject, F> = {
-    [K in keyof z.infer<Z>]: K extends keyof F ? FieldFromOverride<F[K], z.infer<Z>[K]> : FieldBuilder<z.infer<Z>[K]>;
+type MergedFieldsFromZodObject<Z extends z.ZodObject, F, Om extends readonly string[] = readonly [], AI extends string | undefined = undefined> = {
+    [K in keyof Z["shape"] as K extends Om[number] ? never : K]: K extends keyof F ? FieldFromOverride<F[K], AutoFieldFromZod<K, Z["shape"][K], AI>> : AutoFieldFromZod<K, Z["shape"][K], AI>;
 };
 /** Non-`fields` portion of the opts — shared across the public type and
  * the function's inferred-`F` signature. Tracks `EntityDef` so any new
@@ -56,8 +136,15 @@ export interface EntityFromZodOpts<Z extends z.ZodObject = z.ZodObject> extends
      *     });
      */
     fields?: {
-        [K in keyof z.infer<Z> & string]?: EntityFromZodFieldOverride<z.infer<Z>[K]>;
+        [K in keyof Z["shape"] & string]?: AnyFieldBuilder | ((auto: AutoFieldFromZod<K, Z["shape"][K]>) => AnyFieldBuilder);
     };
+    /** Fields whose Zod name ends with this suffix pick up `.indexed()` —
+     * intended for the common FK-naming convention (`/ID$/` → `autoIndex: "ID"`).
+     * Suppressed for any key that supplies a builder-form override. */
+    autoIndex?: string;
+    /** Field names to drop entirely from the produced entity. Common when the
+     * source Zod was generated from a DTO that carries transport-only keys. */
+    omit?: readonly string[];
 }
 /**
  * Convert a `z.object({ ... })` into an `EntityDef`. Each key on the Zod
@@ -84,7 +171,33 @@ export interface EntityFromZodOpts<Z extends z.ZodObject = z.ZodObject> extends
  * shape and validation; `link(...)` remains the source of truth for the
  * graph.
  */
-export declare function entityFromZod<Z extends z.ZodObject, const F = Record<never, never>>(zSchema: Z, opts: EntityFromZodOptsBase & {
-    fields?: F & EntityFromZodFieldOverrides<Z> & NoExtraZodFieldKeys<Z, F>;
-}): EntityDef<MergedFieldsFromZodObject<Z, F>>;
+export declare function entityFromZod<Z extends z.ZodObject, const F = Record<never, never>, const Om extends readonly (keyof Z["shape"] & string)[] = readonly [], const AI extends string | undefined = undefined>(zSchema: Z, opts: EntityFromZodOptsBase & {
+    fields?: F & EntityFromZodFieldOverrides<Z, AI> & NoExtraZodFieldKeys<Z, F>;
+    autoIndex?: AI;
+    omit?: Om;
+}): EntityDef<MergedFieldsFromZodObject<Z, F, Om, AI>>;
+/**
+ * Map a whole `{key: ZodObject}` module (e.g. an OpenAPI-generated barrel)
+ * into an entities record by calling `entityFromZod` per key with shared
+ * opts. The entity key in the returned record is the input key; the registry
+ * name is auto-derived (PascalCase of the key) by `compileSchema` — no need
+ * to spell `name` per entity.
+ *
+ *     const entities = entitiesFromZod(generatedZods, {
+ *       loadStrategy: LoadStrategy.Eager,
+ *       autoIndex: "ID",
+ *       omit: ["createdAt", "updatedAt"],
+ *     });
+ *     const schema = defineSchema({ entities, links: { ... } });
+ *
+ * Per-entity overrides are not threaded — drop down to `entityFromZod` for
+ * the handful that need a custom `fields` map or distinct `loadStrategy`.
+ */
+type EntitiesFromZodResult<Zods extends Record<string, z.ZodObject>, Om extends readonly string[], AI extends string | undefined> = {
+    [K in keyof Zods]: EntityDef<MergedFieldsFromZodObject<Zods[K], Record<never, never>, Om, AI>>;
+};
+export declare function entitiesFromZod<Zods extends Record<string, z.ZodObject>, const Om extends readonly string[] = readonly [], const AI extends string | undefined = undefined>(zods: Zods, opts: Pick<EntityFromZodOptsBase, "loadStrategy" | "usedForPartialIndexes"> & {
+    autoIndex?: AI;
+    omit?: Om;
+}): EntitiesFromZodResult<Zods, Om, AI>;
 export {};

package/dist/schema/zod.js

@@ -82,9 +82,19 @@ export function fromZod(zSchema) {
  */
 export function entityFromZod(zSchema, opts) {
     const overrides = (opts.fields ?? {});
+    const omitted = new Set(opts.omit ?? []);
+    const autoIndexSuffix = opts.autoIndex != null && opts.autoIndex !== "" ? opts.autoIndex : null;
     const fieldsRecord = {};
     for (const [key, fieldSchema] of Object.entries(zSchema.shape)) {
-        const auto = key === "id" ? fields.id() : fromZod(fieldSchema);
+        if (omitted.has(key)) {
+            continue;
+        }
+        let auto = key === "id" ? fields.id() : fromZod(fieldSchema);
+        if (autoIndexSuffix != null &&
+            key !== "id" &&
+            key.endsWith(autoIndexSuffix)) {
+            auto = auto.indexed();
+        }
         const override = overrides[key];
         fieldsRecord[key] =
             typeof override === "function"
@@ -99,3 +109,15 @@ export function entityFromZod(zSchema, opts) {
         fields: fieldsRecord,
     });
 }
+export function entitiesFromZod(zods, opts) {
+    const out = {};
+    for (const [key, zod] of Object.entries(zods)) {
+        out[key] = entityFromZod(zod, {
+            loadStrategy: opts.loadStrategy,
+            usedForPartialIndexes: opts.usedForPartialIndexes,
+            autoIndex: opts.autoIndex,
+            omit: opts.omit,
+        });
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zerodrift",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "private": false,
   "description": "A TypeScript local-first sync engine: synchronous in-memory reads, optimistic writes, realtime SSE sync, offline IndexedDB persistence. Runs in the browser and in Node.",
   "license": "MIT",