@korajs/core 0.4.0 → 0.6.0

package/dist/bindings/index.cjs

@@ -0,0 +1,105 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/bindings/index.ts
+var bindings_exports = {};
+__export(bindings_exports, {
+  createMutationController: () => createMutationController
+});
+module.exports = __toCommonJS(bindings_exports);
+
+// src/bindings/create-mutation-controller.ts
+function createMutationController(options) {
+  let snapshot = { isLoading: false, error: null };
+  const listeners = /* @__PURE__ */ new Set();
+  let disposed = false;
+  let inFlight = 0;
+  const notify = () => {
+    for (const listener of listeners) {
+      listener();
+    }
+    options.onStateChange?.(snapshot);
+  };
+  const setSnapshot = (next) => {
+    snapshot = next;
+    notify();
+  };
+  const getSnapshot = () => snapshot;
+  const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  };
+  const reset = () => {
+    if (disposed) return;
+    setSnapshot({ isLoading: false, error: null });
+  };
+  const mutateAsync = async (...args) => {
+    if (disposed) {
+      throw new Error("Mutation controller is destroyed");
+    }
+    const opts = options.resolveOptions?.() ?? options.options;
+    let context;
+    inFlight++;
+    setSnapshot({ isLoading: true, error: null });
+    try {
+      if (opts?.onMutate) {
+        context = await opts.onMutate(...args);
+      }
+      const result = await options.mutationFn(...args);
+      inFlight = Math.max(0, inFlight - 1);
+      setSnapshot({ isLoading: inFlight > 0, error: null });
+      opts?.onSuccess?.(result, ...args);
+      opts?.onSettled?.(result, null, ...args);
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      if (context !== void 0 && opts?.onRollback) {
+        await opts.onRollback(context, ...args);
+      }
+      inFlight = Math.max(0, inFlight - 1);
+      setSnapshot({ isLoading: inFlight > 0, error });
+      opts?.onError?.(error, ...args);
+      opts?.onSettled?.(void 0, error, ...args);
+      throw error;
+    }
+  };
+  const mutate = (...args) => {
+    void mutateAsync(...args).catch(() => {
+    });
+  };
+  const destroy = () => {
+    disposed = true;
+    listeners.clear();
+  };
+  return {
+    getSnapshot,
+    subscribe,
+    mutate,
+    mutateAsync,
+    reset,
+    destroy
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createMutationController
+});
+//# sourceMappingURL=index.cjs.map

package/dist/bindings/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/bindings/index.ts","../../src/bindings/create-mutation-controller.ts"],"sourcesContent":["export type {\n\tAuthSyncBinding,\n\tKoraAppLike,\n\tKoraBindingSyncBridge,\n\tKoraBindingSyncStatus,\n\tKoraContextValue,\n\tUseMutationOptions,\n\tUseMutationResultBase,\n\tUseQueryOptions,\n} from './types'\nexport {\n\tcreateMutationController,\n\ttype CreateMutationControllerOptions,\n\ttype MutationController,\n\ttype MutationControllerState,\n} from './create-mutation-controller'\n","import type { UseMutationOptions } from './types'\n\nexport interface MutationControllerState {\n\tisLoading: boolean\n\terror: Error | null\n}\n\nexport interface MutationController<TData, TArgs extends unknown[], TContext = void> {\n\tgetSnapshot(): MutationControllerState\n\tsubscribe(listener: () => void): () => void\n\tmutate(...args: TArgs): void\n\tmutateAsync(...args: TArgs): Promise<TData>\n\treset(): void\n\tdestroy(): void\n}\n\nexport interface CreateMutationControllerOptions<TData, TArgs extends unknown[], TContext = void> {\n\tmutationFn: (...args: TArgs) => Promise<TData>\n\toptions?: UseMutationOptions<TData, TArgs, TContext>\n\t/** Reads latest options on each mutation (for framework hooks with ref-backed options). */\n\tresolveOptions?: () => UseMutationOptions<TData, TArgs, TContext> | undefined\n\tonStateChange?: (state: MutationControllerState) => void\n}\n\n/**\n * Framework-agnostic mutation runner with optimistic lifecycle hooks.\n */\nexport function createMutationController<TData, TArgs extends unknown[], TContext = void>(\n\toptions: CreateMutationControllerOptions<TData, TArgs, TContext>,\n): MutationController<TData, TArgs, TContext> {\n\tlet snapshot: MutationControllerState = { isLoading: false, error: null }\n\tconst listeners = new Set<() => void>()\n\tlet disposed = false\n\tlet inFlight = 0\n\n\tconst notify = (): void => {\n\t\tfor (const listener of listeners) {\n\t\t\tlistener()\n\t\t}\n\t\toptions.onStateChange?.(snapshot)\n\t}\n\n\tconst setSnapshot = (next: MutationControllerState): void => {\n\t\tsnapshot = next\n\t\tnotify()\n\t}\n\n\tconst getSnapshot = (): MutationControllerState => snapshot\n\n\tconst subscribe = (listener: () => void): (() => void) => {\n\t\tlisteners.add(listener)\n\t\treturn () => {\n\t\t\tlisteners.delete(listener)\n\t\t}\n\t}\n\n\tconst reset = (): void => {\n\t\tif (disposed) return\n\t\tsetSnapshot({ isLoading: false, error: null })\n\t}\n\n\tconst mutateAsync = async (...args: TArgs): Promise<TData> => {\n\t\tif (disposed) {\n\t\t\tthrow new Error('Mutation controller is destroyed')\n\t\t}\n\n\t\tconst opts = options.resolveOptions?.() ?? options.options\n\t\tlet context: TContext | undefined\n\n\t\tinFlight++\n\t\tsetSnapshot({ isLoading: true, error: null })\n\n\t\ttry {\n\t\t\tif (opts?.onMutate) {\n\t\t\t\tcontext = await opts.onMutate(...args)\n\t\t\t}\n\n\t\t\tconst result = await options.mutationFn(...args)\n\t\t\tinFlight = Math.max(0, inFlight - 1)\n\t\t\tsetSnapshot({ isLoading: inFlight > 0, error: null })\n\t\t\topts?.onSuccess?.(result, ...args)\n\t\t\topts?.onSettled?.(result, null, ...args)\n\t\t\treturn result\n\t\t} catch (err) {\n\t\t\tconst error = err instanceof Error ? err : new Error(String(err))\n\n\t\t\tif (context !== undefined && opts?.onRollback) {\n\t\t\t\tawait opts.onRollback(context, ...args)\n\t\t\t}\n\n\t\t\tinFlight = Math.max(0, inFlight - 1)\n\t\t\tsetSnapshot({ isLoading: inFlight > 0, error })\n\t\t\topts?.onError?.(error, ...args)\n\t\t\topts?.onSettled?.(undefined, error, ...args)\n\t\t\tthrow error\n\t\t}\n\t}\n\n\tconst mutate = (...args: TArgs): void => {\n\t\tvoid mutateAsync(...args).catch(() => {})\n\t}\n\n\tconst destroy = (): void => {\n\t\tdisposed = true\n\t\tlisteners.clear()\n\t}\n\n\treturn {\n\t\tgetSnapshot,\n\t\tsubscribe,\n\t\tmutate,\n\t\tmutateAsync,\n\t\treset,\n\t\tdestroy,\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC2BO,SAAS,yBACf,SAC6C;AAC7C,MAAI,WAAoC,EAAE,WAAW,OAAO,OAAO,KAAK;AACxE,QAAM,YAAY,oBAAI,IAAgB;AACtC,MAAI,WAAW;AACf,MAAI,WAAW;AAEf,QAAM,SAAS,MAAY;AAC1B,eAAW,YAAY,WAAW;AACjC,eAAS;AAAA,IACV;AACA,YAAQ,gBAAgB,QAAQ;AAAA,EACjC;AAEA,QAAM,cAAc,CAAC,SAAwC;AAC5D,eAAW;AACX,WAAO;AAAA,EACR;AAEA,QAAM,cAAc,MAA+B;AAEnD,QAAM,YAAY,CAAC,aAAuC;AACzD,cAAU,IAAI,QAAQ;AACtB,WAAO,MAAM;AACZ,gBAAU,OAAO,QAAQ;AAAA,IAC1B;AAAA,EACD;AAEA,QAAM,QAAQ,MAAY;AACzB,QAAI,SAAU;AACd,gBAAY,EAAE,WAAW,OAAO,OAAO,KAAK,CAAC;AAAA,EAC9C;AAEA,QAAM,cAAc,UAAU,SAAgC;AAC7D,QAAI,UAAU;AACb,YAAM,IAAI,MAAM,kCAAkC;AAAA,IACnD;AAEA,UAAM,OAAO,QAAQ,iBAAiB,KAAK,QAAQ;AACnD,QAAI;AAEJ;AACA,gBAAY,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AAE5C,QAAI;AACH,UAAI,MAAM,UAAU;AACnB,kBAAU,MAAM,KAAK,SAAS,GAAG,IAAI;AAAA,MACtC;AAEA,YAAM,SAAS,MAAM,QAAQ,WAAW,GAAG,IAAI;AAC/C,iBAAW,KAAK,IAAI,GAAG,WAAW,CAAC;AACnC,kBAAY,EAAE,WAAW,WAAW,GAAG,OAAO,KAAK,CAAC;AACpD,YAAM,YAAY,QAAQ,GAAG,IAAI;AACjC,YAAM,YAAY,QAAQ,MAAM,GAAG,IAAI;AACvC,aAAO;AAAA,IACR,SAAS,KAAK;AACb,YAAM,QAAQ,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAEhE,UAAI,YAAY,UAAa,MAAM,YAAY;AAC9C,cAAM,KAAK,WAAW,SAAS,GAAG,IAAI;AAAA,MACvC;AAEA,iBAAW,KAAK,IAAI,GAAG,WAAW,CAAC;AACnC,kBAAY,EAAE,WAAW,WAAW,GAAG,MAAM,CAAC;AAC9C,YAAM,UAAU,OAAO,GAAG,IAAI;AAC9B,YAAM,YAAY,QAAW,OAAO,GAAG,IAAI;AAC3C,YAAM;AAAA,IACP;AAAA,EACD;AAEA,QAAM,SAAS,IAAI,SAAsB;AACxC,SAAK,YAAY,GAAG,IAAI,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACzC;AAEA,QAAM,UAAU,MAAY;AAC3B,eAAW;AACX,cAAU,MAAM;AAAA,EACjB;AAEA,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACD;AACD;","names":[]}

package/dist/bindings/index.d.cts

@@ -0,0 +1,101 @@
+import { p as KoraEventEmitter } from '../events-D-FWfFg8.cjs';
+import { S as ScopeMap } from '../build-scope-map-B1CcncZN.cjs';
+
+/** Sync status shape consumed by framework binding hooks (matches {@link SyncStatusInfo} in `@korajs/sync`). */
+interface KoraBindingSyncStatus {
+    status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch';
+    pendingOperations: number;
+    lastSyncedAt: number | null;
+    lastSuccessfulPush: number | null;
+    lastSuccessfulPull: number | null;
+    conflicts: number;
+}
+/** Minimal sync bridge surface exposed on `createApp().sync`. */
+interface KoraBindingSyncBridge {
+    subscribeStatus(listener: (status: KoraBindingSyncStatus) => void): () => void;
+}
+/**
+ * Structural type for a Kora application instance from `createApp()`.
+ * Framework packages specialize `TStore` and `TSyncEngine` with concrete types.
+ */
+interface KoraAppLike<TStore = unknown, TSyncEngine = unknown, TQueryCache = unknown> {
+    ready: Promise<void>;
+    events?: KoraEventEmitter;
+    sync?: KoraBindingSyncBridge | null;
+    getStore(): TStore;
+    getSyncEngine(): TSyncEngine | null;
+    getQueryStoreCache(): TQueryCache;
+}
+/** Value provided by framework `KoraProvider` implementations. */
+interface KoraContextValue<TStore = unknown, TSyncEngine = unknown, TQueryCache = unknown> {
+    store: TStore;
+    syncEngine: TSyncEngine | null;
+    app: KoraAppLike<TStore, TSyncEngine, TQueryCache> | null;
+    events: KoraEventEmitter | null;
+    subscribeSyncStatus: KoraBindingSyncBridge['subscribeStatus'] | null;
+    queryStoreCache: TQueryCache;
+}
+/** Options for reactive query bindings (`useQuery`, `createQueryStore`, etc.). */
+interface UseQueryOptions {
+    /** When false, the query subscription is disabled. Defaults to true. */
+    enabled?: boolean;
+}
+/** Optimistic mutation lifecycle callbacks shared across framework bindings. */
+interface UseMutationOptions<TData, TArgs extends unknown[], TContext = void> {
+    onMutate?: (...args: TArgs) => TContext | Promise<TContext>;
+    onRollback?: (context: TContext, ...args: TArgs) => void | Promise<void>;
+    onSuccess?: (data: TData, ...args: TArgs) => void;
+    onError?: (error: Error, ...args: TArgs) => void;
+    onSettled?: (data: TData | undefined, error: Error | null, ...args: TArgs) => void;
+}
+/** Common mutation result surface (React uses plain values; Vue/Svelte extend this). */
+interface UseMutationResultBase<TData, TArgs extends unknown[]> {
+    mutate: (...args: TArgs) => void;
+    mutateAsync: (...args: TArgs) => Promise<TData>;
+    reset: () => void;
+}
+/**
+ * Pre-built auth binding for `createApp({ sync: { authClient } })`.
+ * Created by `createKoraAuthSync()` in `@korajs/auth`.
+ */
+interface AuthSyncBinding {
+    /** Returns the access token for sync handshake (empty string when signed out). */
+    auth: () => Promise<{
+        token: string;
+    }>;
+    /** Builds a scope map from the current token and schema. */
+    resolveScopeMap?: () => Promise<ScopeMap | undefined>;
+    /**
+     * Returns the device-bound sync node id from the token `dev` claim.
+     * Separate from the user id (`sub`).
+     */
+    resolveNodeId?: () => Promise<string | undefined>;
+    /** Notifies when auth state changes so sync can refresh scope or reconnect. */
+    subscribe?: (listener: () => void) => () => void;
+}
+
+interface MutationControllerState {
+    isLoading: boolean;
+    error: Error | null;
+}
+interface MutationController<TData, TArgs extends unknown[], TContext = void> {
+    getSnapshot(): MutationControllerState;
+    subscribe(listener: () => void): () => void;
+    mutate(...args: TArgs): void;
+    mutateAsync(...args: TArgs): Promise<TData>;
+    reset(): void;
+    destroy(): void;
+}
+interface CreateMutationControllerOptions<TData, TArgs extends unknown[], TContext = void> {
+    mutationFn: (...args: TArgs) => Promise<TData>;
+    options?: UseMutationOptions<TData, TArgs, TContext>;
+    /** Reads latest options on each mutation (for framework hooks with ref-backed options). */
+    resolveOptions?: () => UseMutationOptions<TData, TArgs, TContext> | undefined;
+    onStateChange?: (state: MutationControllerState) => void;
+}
+/**
+ * Framework-agnostic mutation runner with optimistic lifecycle hooks.
+ */
+declare function createMutationController<TData, TArgs extends unknown[], TContext = void>(options: CreateMutationControllerOptions<TData, TArgs, TContext>): MutationController<TData, TArgs, TContext>;
+
+export { type AuthSyncBinding, type CreateMutationControllerOptions, type KoraAppLike, type KoraBindingSyncBridge, type KoraBindingSyncStatus, type KoraContextValue, type MutationController, type MutationControllerState, type UseMutationOptions, type UseMutationResultBase, type UseQueryOptions, createMutationController };

package/dist/bindings/index.d.ts

@@ -0,0 +1,101 @@
+import { p as KoraEventEmitter } from '../events-D-FWfFg8.js';
+import { S as ScopeMap } from '../build-scope-map-BmgAT82h.js';
+
+/** Sync status shape consumed by framework binding hooks (matches {@link SyncStatusInfo} in `@korajs/sync`). */
+interface KoraBindingSyncStatus {
+    status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error' | 'schema-mismatch';
+    pendingOperations: number;
+    lastSyncedAt: number | null;
+    lastSuccessfulPush: number | null;
+    lastSuccessfulPull: number | null;
+    conflicts: number;
+}
+/** Minimal sync bridge surface exposed on `createApp().sync`. */
+interface KoraBindingSyncBridge {
+    subscribeStatus(listener: (status: KoraBindingSyncStatus) => void): () => void;
+}
+/**
+ * Structural type for a Kora application instance from `createApp()`.
+ * Framework packages specialize `TStore` and `TSyncEngine` with concrete types.
+ */
+interface KoraAppLike<TStore = unknown, TSyncEngine = unknown, TQueryCache = unknown> {
+    ready: Promise<void>;
+    events?: KoraEventEmitter;
+    sync?: KoraBindingSyncBridge | null;
+    getStore(): TStore;
+    getSyncEngine(): TSyncEngine | null;
+    getQueryStoreCache(): TQueryCache;
+}
+/** Value provided by framework `KoraProvider` implementations. */
+interface KoraContextValue<TStore = unknown, TSyncEngine = unknown, TQueryCache = unknown> {
+    store: TStore;
+    syncEngine: TSyncEngine | null;
+    app: KoraAppLike<TStore, TSyncEngine, TQueryCache> | null;
+    events: KoraEventEmitter | null;
+    subscribeSyncStatus: KoraBindingSyncBridge['subscribeStatus'] | null;
+    queryStoreCache: TQueryCache;
+}
+/** Options for reactive query bindings (`useQuery`, `createQueryStore`, etc.). */
+interface UseQueryOptions {
+    /** When false, the query subscription is disabled. Defaults to true. */
+    enabled?: boolean;
+}
+/** Optimistic mutation lifecycle callbacks shared across framework bindings. */
+interface UseMutationOptions<TData, TArgs extends unknown[], TContext = void> {
+    onMutate?: (...args: TArgs) => TContext | Promise<TContext>;
+    onRollback?: (context: TContext, ...args: TArgs) => void | Promise<void>;
+    onSuccess?: (data: TData, ...args: TArgs) => void;
+    onError?: (error: Error, ...args: TArgs) => void;
+    onSettled?: (data: TData | undefined, error: Error | null, ...args: TArgs) => void;
+}
+/** Common mutation result surface (React uses plain values; Vue/Svelte extend this). */
+interface UseMutationResultBase<TData, TArgs extends unknown[]> {
+    mutate: (...args: TArgs) => void;
+    mutateAsync: (...args: TArgs) => Promise<TData>;
+    reset: () => void;
+}
+/**
+ * Pre-built auth binding for `createApp({ sync: { authClient } })`.
+ * Created by `createKoraAuthSync()` in `@korajs/auth`.
+ */
+interface AuthSyncBinding {
+    /** Returns the access token for sync handshake (empty string when signed out). */
+    auth: () => Promise<{
+        token: string;
+    }>;
+    /** Builds a scope map from the current token and schema. */
+    resolveScopeMap?: () => Promise<ScopeMap | undefined>;
+    /**
+     * Returns the device-bound sync node id from the token `dev` claim.
+     * Separate from the user id (`sub`).
+     */
+    resolveNodeId?: () => Promise<string | undefined>;
+    /** Notifies when auth state changes so sync can refresh scope or reconnect. */
+    subscribe?: (listener: () => void) => () => void;
+}
+
+interface MutationControllerState {
+    isLoading: boolean;
+    error: Error | null;
+}
+interface MutationController<TData, TArgs extends unknown[], TContext = void> {
+    getSnapshot(): MutationControllerState;
+    subscribe(listener: () => void): () => void;
+    mutate(...args: TArgs): void;
+    mutateAsync(...args: TArgs): Promise<TData>;
+    reset(): void;
+    destroy(): void;
+}
+interface CreateMutationControllerOptions<TData, TArgs extends unknown[], TContext = void> {
+    mutationFn: (...args: TArgs) => Promise<TData>;
+    options?: UseMutationOptions<TData, TArgs, TContext>;
+    /** Reads latest options on each mutation (for framework hooks with ref-backed options). */
+    resolveOptions?: () => UseMutationOptions<TData, TArgs, TContext> | undefined;
+    onStateChange?: (state: MutationControllerState) => void;
+}
+/**
+ * Framework-agnostic mutation runner with optimistic lifecycle hooks.
+ */
+declare function createMutationController<TData, TArgs extends unknown[], TContext = void>(options: CreateMutationControllerOptions<TData, TArgs, TContext>): MutationController<TData, TArgs, TContext>;
+
+export { type AuthSyncBinding, type CreateMutationControllerOptions, type KoraAppLike, type KoraBindingSyncBridge, type KoraBindingSyncStatus, type KoraContextValue, type MutationController, type MutationControllerState, type UseMutationOptions, type UseMutationResultBase, type UseQueryOptions, createMutationController };

package/dist/bindings/index.js

@@ -0,0 +1,78 @@
+// src/bindings/create-mutation-controller.ts
+function createMutationController(options) {
+  let snapshot = { isLoading: false, error: null };
+  const listeners = /* @__PURE__ */ new Set();
+  let disposed = false;
+  let inFlight = 0;
+  const notify = () => {
+    for (const listener of listeners) {
+      listener();
+    }
+    options.onStateChange?.(snapshot);
+  };
+  const setSnapshot = (next) => {
+    snapshot = next;
+    notify();
+  };
+  const getSnapshot = () => snapshot;
+  const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  };
+  const reset = () => {
+    if (disposed) return;
+    setSnapshot({ isLoading: false, error: null });
+  };
+  const mutateAsync = async (...args) => {
+    if (disposed) {
+      throw new Error("Mutation controller is destroyed");
+    }
+    const opts = options.resolveOptions?.() ?? options.options;
+    let context;
+    inFlight++;
+    setSnapshot({ isLoading: true, error: null });
+    try {
+      if (opts?.onMutate) {
+        context = await opts.onMutate(...args);
+      }
+      const result = await options.mutationFn(...args);
+      inFlight = Math.max(0, inFlight - 1);
+      setSnapshot({ isLoading: inFlight > 0, error: null });
+      opts?.onSuccess?.(result, ...args);
+      opts?.onSettled?.(result, null, ...args);
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      if (context !== void 0 && opts?.onRollback) {
+        await opts.onRollback(context, ...args);
+      }
+      inFlight = Math.max(0, inFlight - 1);
+      setSnapshot({ isLoading: inFlight > 0, error });
+      opts?.onError?.(error, ...args);
+      opts?.onSettled?.(void 0, error, ...args);
+      throw error;
+    }
+  };
+  const mutate = (...args) => {
+    void mutateAsync(...args).catch(() => {
+    });
+  };
+  const destroy = () => {
+    disposed = true;
+    listeners.clear();
+  };
+  return {
+    getSnapshot,
+    subscribe,
+    mutate,
+    mutateAsync,
+    reset,
+    destroy
+  };
+}
+export {
+  createMutationController
+};
+//# sourceMappingURL=index.js.map

package/dist/bindings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/bindings/create-mutation-controller.ts"],"sourcesContent":["import type { UseMutationOptions } from './types'\n\nexport interface MutationControllerState {\n\tisLoading: boolean\n\terror: Error | null\n}\n\nexport interface MutationController<TData, TArgs extends unknown[], TContext = void> {\n\tgetSnapshot(): MutationControllerState\n\tsubscribe(listener: () => void): () => void\n\tmutate(...args: TArgs): void\n\tmutateAsync(...args: TArgs): Promise<TData>\n\treset(): void\n\tdestroy(): void\n}\n\nexport interface CreateMutationControllerOptions<TData, TArgs extends unknown[], TContext = void> {\n\tmutationFn: (...args: TArgs) => Promise<TData>\n\toptions?: UseMutationOptions<TData, TArgs, TContext>\n\t/** Reads latest options on each mutation (for framework hooks with ref-backed options). */\n\tresolveOptions?: () => UseMutationOptions<TData, TArgs, TContext> | undefined\n\tonStateChange?: (state: MutationControllerState) => void\n}\n\n/**\n * Framework-agnostic mutation runner with optimistic lifecycle hooks.\n */\nexport function createMutationController<TData, TArgs extends unknown[], TContext = void>(\n\toptions: CreateMutationControllerOptions<TData, TArgs, TContext>,\n): MutationController<TData, TArgs, TContext> {\n\tlet snapshot: MutationControllerState = { isLoading: false, error: null }\n\tconst listeners = new Set<() => void>()\n\tlet disposed = false\n\tlet inFlight = 0\n\n\tconst notify = (): void => {\n\t\tfor (const listener of listeners) {\n\t\t\tlistener()\n\t\t}\n\t\toptions.onStateChange?.(snapshot)\n\t}\n\n\tconst setSnapshot = (next: MutationControllerState): void => {\n\t\tsnapshot = next\n\t\tnotify()\n\t}\n\n\tconst getSnapshot = (): MutationControllerState => snapshot\n\n\tconst subscribe = (listener: () => void): (() => void) => {\n\t\tlisteners.add(listener)\n\t\treturn () => {\n\t\t\tlisteners.delete(listener)\n\t\t}\n\t}\n\n\tconst reset = (): void => {\n\t\tif (disposed) return\n\t\tsetSnapshot({ isLoading: false, error: null })\n\t}\n\n\tconst mutateAsync = async (...args: TArgs): Promise<TData> => {\n\t\tif (disposed) {\n\t\t\tthrow new Error('Mutation controller is destroyed')\n\t\t}\n\n\t\tconst opts = options.resolveOptions?.() ?? options.options\n\t\tlet context: TContext | undefined\n\n\t\tinFlight++\n\t\tsetSnapshot({ isLoading: true, error: null })\n\n\t\ttry {\n\t\t\tif (opts?.onMutate) {\n\t\t\t\tcontext = await opts.onMutate(...args)\n\t\t\t}\n\n\t\t\tconst result = await options.mutationFn(...args)\n\t\t\tinFlight = Math.max(0, inFlight - 1)\n\t\t\tsetSnapshot({ isLoading: inFlight > 0, error: null })\n\t\t\topts?.onSuccess?.(result, ...args)\n\t\t\topts?.onSettled?.(result, null, ...args)\n\t\t\treturn result\n\t\t} catch (err) {\n\t\t\tconst error = err instanceof Error ? err : new Error(String(err))\n\n\t\t\tif (context !== undefined && opts?.onRollback) {\n\t\t\t\tawait opts.onRollback(context, ...args)\n\t\t\t}\n\n\t\t\tinFlight = Math.max(0, inFlight - 1)\n\t\t\tsetSnapshot({ isLoading: inFlight > 0, error })\n\t\t\topts?.onError?.(error, ...args)\n\t\t\topts?.onSettled?.(undefined, error, ...args)\n\t\t\tthrow error\n\t\t}\n\t}\n\n\tconst mutate = (...args: TArgs): void => {\n\t\tvoid mutateAsync(...args).catch(() => {})\n\t}\n\n\tconst destroy = (): void => {\n\t\tdisposed = true\n\t\tlisteners.clear()\n\t}\n\n\treturn {\n\t\tgetSnapshot,\n\t\tsubscribe,\n\t\tmutate,\n\t\tmutateAsync,\n\t\treset,\n\t\tdestroy,\n\t}\n}\n"],"mappings":";AA2BO,SAAS,yBACf,SAC6C;AAC7C,MAAI,WAAoC,EAAE,WAAW,OAAO,OAAO,KAAK;AACxE,QAAM,YAAY,oBAAI,IAAgB;AACtC,MAAI,WAAW;AACf,MAAI,WAAW;AAEf,QAAM,SAAS,MAAY;AAC1B,eAAW,YAAY,WAAW;AACjC,eAAS;AAAA,IACV;AACA,YAAQ,gBAAgB,QAAQ;AAAA,EACjC;AAEA,QAAM,cAAc,CAAC,SAAwC;AAC5D,eAAW;AACX,WAAO;AAAA,EACR;AAEA,QAAM,cAAc,MAA+B;AAEnD,QAAM,YAAY,CAAC,aAAuC;AACzD,cAAU,IAAI,QAAQ;AACtB,WAAO,MAAM;AACZ,gBAAU,OAAO,QAAQ;AAAA,IAC1B;AAAA,EACD;AAEA,QAAM,QAAQ,MAAY;AACzB,QAAI,SAAU;AACd,gBAAY,EAAE,WAAW,OAAO,OAAO,KAAK,CAAC;AAAA,EAC9C;AAEA,QAAM,cAAc,UAAU,SAAgC;AAC7D,QAAI,UAAU;AACb,YAAM,IAAI,MAAM,kCAAkC;AAAA,IACnD;AAEA,UAAM,OAAO,QAAQ,iBAAiB,KAAK,QAAQ;AACnD,QAAI;AAEJ;AACA,gBAAY,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AAE5C,QAAI;AACH,UAAI,MAAM,UAAU;AACnB,kBAAU,MAAM,KAAK,SAAS,GAAG,IAAI;AAAA,MACtC;AAEA,YAAM,SAAS,MAAM,QAAQ,WAAW,GAAG,IAAI;AAC/C,iBAAW,KAAK,IAAI,GAAG,WAAW,CAAC;AACnC,kBAAY,EAAE,WAAW,WAAW,GAAG,OAAO,KAAK,CAAC;AACpD,YAAM,YAAY,QAAQ,GAAG,IAAI;AACjC,YAAM,YAAY,QAAQ,MAAM,GAAG,IAAI;AACvC,aAAO;AAAA,IACR,SAAS,KAAK;AACb,YAAM,QAAQ,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAEhE,UAAI,YAAY,UAAa,MAAM,YAAY;AAC9C,cAAM,KAAK,WAAW,SAAS,GAAG,IAAI;AAAA,MACvC;AAEA,iBAAW,KAAK,IAAI,GAAG,WAAW,CAAC;AACnC,kBAAY,EAAE,WAAW,WAAW,GAAG,MAAM,CAAC;AAC9C,YAAM,UAAU,OAAO,GAAG,IAAI;AAC9B,YAAM,YAAY,QAAW,OAAO,GAAG,IAAI;AAC3C,YAAM;AAAA,IACP;AAAA,EACD;AAEA,QAAM,SAAS,IAAI,SAAsB;AACxC,SAAK,YAAY,GAAG,IAAI,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACzC;AAEA,QAAM,UAAU,MAAY;AAC3B,eAAW;AACX,cAAU,MAAM;AAAA,EACjB;AAEA,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACD;AACD;","names":[]}

package/dist/build-scope-map-B1CcncZN.d.cts

@@ -0,0 +1,33 @@
+import { S as SchemaDefinition } from './events-D-FWfFg8.cjs';
+
+/**
+ * Per-collection scope map: `{ collectionName: { field: value, ... } }`
+ *
+ * Used to filter which operations a client should receive during sync.
+ */
+type ScopeMap = Record<string, Record<string, unknown>>;
+/**
+ * Build a per-collection scope map from the schema's scope declarations
+ * and the client's flat scope values.
+ *
+ * Supports both legacy `collection.scope` arrays and declarative `schema.sync`
+ * rules (`sync: { todos: { where: { userId: true } } }`).
+ *
+ * When `schema.sync` is present, only collections with sync rules or legacy
+ * scope fields are included in the result. Other collections are omitted so
+ * sync engines treat them as out of scope (partial sync).
+ *
+ * @param schema - The schema definition with scope declarations
+ * @param scopeValues - Flat key-value scope values from the client
+ * @returns A per-collection scope map
+ *
+ * @example
+ * ```typescript
+ * // Schema declares: sales.scope = ['orgId', 'storeId']
+ * // Client provides: { orgId: 'org-123', storeId: 'store-456' }
+ * // Result: { sales: { orgId: 'org-123', storeId: 'store-456' }, products: {} }
+ * ```
+ */
+declare function buildScopeMap(schema: SchemaDefinition, scopeValues: Record<string, unknown>): ScopeMap;
+
+export { type ScopeMap as S, buildScopeMap as b };

package/dist/build-scope-map-BmgAT82h.d.ts

@@ -0,0 +1,33 @@
+import { S as SchemaDefinition } from './events-D-FWfFg8.js';
+
+/**
+ * Per-collection scope map: `{ collectionName: { field: value, ... } }`
+ *
+ * Used to filter which operations a client should receive during sync.
+ */
+type ScopeMap = Record<string, Record<string, unknown>>;
+/**
+ * Build a per-collection scope map from the schema's scope declarations
+ * and the client's flat scope values.
+ *
+ * Supports both legacy `collection.scope` arrays and declarative `schema.sync`
+ * rules (`sync: { todos: { where: { userId: true } } }`).
+ *
+ * When `schema.sync` is present, only collections with sync rules or legacy
+ * scope fields are included in the result. Other collections are omitted so
+ * sync engines treat them as out of scope (partial sync).
+ *
+ * @param schema - The schema definition with scope declarations
+ * @param scopeValues - Flat key-value scope values from the client
+ * @returns A per-collection scope map
+ *
+ * @example
+ * ```typescript
+ * // Schema declares: sales.scope = ['orgId', 'storeId']
+ * // Client provides: { orgId: 'org-123', storeId: 'store-456' }
+ * // Result: { sales: { orgId: 'org-123', storeId: 'store-456' }, products: {} }
+ * ```
+ */
+declare function buildScopeMap(schema: SchemaDefinition, scopeValues: Record<string, unknown>): ScopeMap;
+
+export { type ScopeMap as S, buildScopeMap as b };

package/dist/{chunk-CFP5YFXC.js → chunk-3VIOZT7D.js}

@@ -1,3 +1,20 @@
+// src/errors/error-fixes.ts
+var KORA_ERROR_FIX_SUGGESTIONS = {
+  SCHEMA_VALIDATION: "Review your defineSchema() definition: every collection needs at least one field and a positive version.",
+  OPERATION_ERROR: "Check the operation payload matches your schema field types and required fields.",
+  MERGE_CONFLICT: "Add a custom resolver for the conflicting field in defineSchema(), or adjust constraint onConflict rules.",
+  SYNC_ERROR: "Verify the sync server URL, auth token, and that the server accepts your schema version.",
+  STORAGE_ERROR: "Confirm the storage adapter is supported in this environment and the database path is writable.",
+  CLOCK_DRIFT: "Sync device wall-clock time (NTP). Kora refuses new timestamps when drift exceeds five minutes.",
+  PERSISTENCE_ERROR: "IndexedDB persistence failed; check browser storage settings and available disk quota.",
+  MISSING_WORKER_URL: "Pass store.workerUrl pointing to sqlite-wasm-worker.js (see create-kora-app templates).",
+  INVALID_SYNC_URL: "Use ws:// or wss:// for WebSocket transport, or http(s):// for HTTP long-polling.",
+  APP_NOT_READY: "Await app.ready before querying or mutating collections, or wrap the tree in <KoraProvider app={app}>."
+};
+function getKoraErrorFix(code) {
+  return KORA_ERROR_FIX_SUGGESTIONS[code];
+}
+
 // src/errors/errors.ts
 var KoraError = class extends Error {
   constructor(message, code, context) {
@@ -8,6 +25,16 @@ var KoraError = class extends Error {
   }
   code;
   context;
+  /**
+   * Actionable hint for resolving this error (from registry or error context).
+   */
+  get fix() {
+    const fromContext = this.context?.fix;
+    if (typeof fromContext === "string" && fromContext.length > 0) {
+      return fromContext;
+    }
+    return getKoraErrorFix(this.code);
+  }
 };
 var SchemaValidationError = class extends KoraError {
   constructor(message, context) {
@@ -49,6 +76,14 @@ var StorageError = class extends KoraError {
     this.name = "StorageError";
   }
 };
+var AppNotReadyError = class extends KoraError {
+  constructor(detail) {
+    super(detail, "APP_NOT_READY", {
+      fix: "Await app.ready, or wrap your UI in <KoraProvider app={app}> before calling useQuery()."
+    });
+    this.name = "AppNotReadyError";
+  }
+};
 var ClockDriftError = class extends KoraError {
   constructor(currentHlcTime, physicalTime) {
     const driftSeconds = Math.round((currentHlcTime - physicalTime) / 1e3);
@@ -105,6 +140,7 @@ var HybridLogicalClock = class {
    */
   receive(remote) {
     const physicalTime = this.timeSource.now();
+    const wasColdStart = this.wallTime === 0;
     if (physicalTime > this.wallTime && physicalTime > remote.wallTime) {
       this.wallTime = physicalTime;
       this.logical = 0;
@@ -116,7 +152,9 @@ var HybridLogicalClock = class {
     } else {
       this.logical++;
     }
-    this.checkDrift(physicalTime);
+    if (!wasColdStart) {
+      this.checkDrift(physicalTime);
+    }
     return { wallTime: this.wallTime, logical: this.logical, nodeId: this.nodeId };
   }
   /**
@@ -184,8 +222,11 @@ async function computeOperationId(input, timestamp) {
   return bufferToHex(hashBuffer);
 }
 function canonicalize(obj) {
-  if (obj === null || obj === void 0) {
-    return JSON.stringify(obj);
+  if (obj === null) {
+    return "null";
+  }
+  if (obj === void 0) {
+    return "null";
   }
   if (typeof obj !== "object") {
     return JSON.stringify(obj);
@@ -197,7 +238,7 @@ function canonicalize(obj) {
   const keys = Object.keys(obj).sort();
   const pairs = keys.map((key) => {
     const value = obj[key];
-    return `${JSON.stringify(key)}:${canonicalize(value)}`;
+    return `${JSON.stringify(key)}:${canonicalize(value === void 0 ? null : value)}`;
   });
   return `{${pairs.join(",")}}`;
 }
@@ -318,6 +359,7 @@ function isValidOperation(value) {
 }
 function deepFreeze(obj) {
   if (typeof obj !== "object" || obj === null) return obj;
+  if (ArrayBuffer.isView(obj)) return obj;
   Object.freeze(obj);
   for (const value of Object.values(obj)) {
     if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
@@ -446,12 +488,15 @@ var MinHeap = class {
 };
 
 export {
+  KORA_ERROR_FIX_SUGGESTIONS,
+  getKoraErrorFix,
   KoraError,
   SchemaValidationError,
   OperationError,
   MergeConflictError,
   SyncError,
   StorageError,
+  AppNotReadyError,
   ClockDriftError,
   HybridLogicalClock,
   computeOperationId,
@@ -462,4 +507,4 @@ export {
   isValidOperation,
   topologicalSort
 };
-//# sourceMappingURL=chunk-CFP5YFXC.js.map
+//# sourceMappingURL=chunk-3VIOZT7D.js.map