js-bao 0.5.1 → 0.5.2

package/dist/client.cjs

@@ -93,37 +93,73 @@ var init_yjsValues = __esm({
   }
 });
 
+// src/models/writeLifecycle.ts
+function registerFunctionDefaultGenerator(name, fn) {
+  FUNCTION_DEFAULT_GENERATORS.set(name, fn);
+}
+var Y2, import_ulid, KNOWN_FIELD_TYPE_MAP, KNOWN_FIELD_TYPES, FUNCTION_DEFAULT_GENERATORS;
+var init_writeLifecycle = __esm({
+  "src/models/writeLifecycle.ts"() {
+    "use strict";
+    Y2 = __toESM(require("yjs"), 1);
+    import_ulid = require("ulid");
+    KNOWN_FIELD_TYPE_MAP = {
+      string: true,
+      number: true,
+      boolean: true,
+      date: true,
+      id: true,
+      stringset: true
+    };
+    KNOWN_FIELD_TYPES = new Set(Object.keys(KNOWN_FIELD_TYPE_MAP));
+    FUNCTION_DEFAULT_GENERATORS = /* @__PURE__ */ new Map();
+    registerFunctionDefaultGenerator("generate_ulid", () => (0, import_ulid.ulid)());
+  }
+});
+
 // src/models/metaSync.ts
 function registerFunctionDefault(fn, name) {
   KNOWN_FUNCTION_DEFAULTS.set(fn, name);
 }
-var Y2, KNOWN_FUNCTION_DEFAULTS;
+var Y3, KNOWN_FUNCTION_DEFAULTS;
 var init_metaSync = __esm({
   "src/models/metaSync.ts"() {
     "use strict";
-    Y2 = __toESM(require("yjs"), 1);
+    Y3 = __toESM(require("yjs"), 1);
     init_yjsValues();
+    init_writeLifecycle();
     KNOWN_FUNCTION_DEFAULTS = /* @__PURE__ */ new WeakMap();
   }
 });
 
+// src/utils/uniqueIndex.ts
+var Y4;
+var init_uniqueIndex = __esm({
+  "src/utils/uniqueIndex.ts"() {
+    "use strict";
+    Y4 = __toESM(require("yjs"), 1);
+  }
+});
+
 // src/models/BaseModel.ts
 function generateULID() {
-  return (0, import_ulid.ulid)();
+  return (0, import_ulid2.ulid)();
 }
-var Y3, import_ulid, Logger;
+var Y5, import_ulid2, Logger;
 var init_BaseModel = __esm({
   "src/models/BaseModel.ts"() {
     "use strict";
-    Y3 = __toESM(require("yjs"), 1);
-    import_ulid = require("ulid");
+    Y5 = __toESM(require("yjs"), 1);
+    import_ulid2 = require("ulid");
     init_StringSet();
     init_documentTypes();
     init_DocumentQueryTranslator();
     init_CursorManager();
     init_sql();
     init_metaSync();
+    init_writeLifecycle();
     init_yjsValues();
+    init_uniqueIndex();
     Logger = class {
       static _logLevel = 1 /* ERROR */;
       static _logCallback = null;

package/dist/client.d.cts

@@ -563,6 +563,27 @@ declare class BaseModel implements StringSetChangeTracker {
      */
     static count(this: new (...args: any[]) => any, filter?: DocumentFilter, options?: Pick<QueryOptions, "documents">): Promise<number>;
     static findAll<T extends BaseModel>(this: new (...args: any[]) => T): Promise<T[]>;
+    /**
+     * Resolve a record by its unique-constraint field values via an engine query.
+     * Used as a fallback when the `_uniqueIdx_<model>_<constraint>` map has no
+     * entry for a key.
+     *
+     * The index map is a cache over the SQLite projection, not the source of
+     * truth: every record is loaded into the projection on `initializeForDocument`
+     * regardless of index presence, but a record written by a client predating
+     * index maintenance (legacy data) is missing from the index. Such a record
+     * silently escapes both `upsertByUnique` lookups and the `save()` uniqueness
+     * check. A query over the constraint fields finds it reliably.
+     *
+     * Contract: RESOLVE ONLY. Returns the owning record (with `_metaDocId` set to
+     * the document that holds it, via `queryOne`) or `null`. Callers decide
+     * whether to heal the missing index entry (write paths) and do their own
+     * logging — this method never mutates the index, so read paths stay
+     * read-only. Mirrors `buildUniqueKey`: a null/undefined value in any
+     * constraint field means the record does not participate in the constraint,
+     * so no query runs.
+     */
+    private static _resolveByUniqueFallback;
     static findByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, value: any | any[]): Promise<T | null>;
     static upsertByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, uniqueLookupValue: any | any[], dataToUpsert: Partial<Omit<InstanceType<new (...args: any[]) => T>, keyof BaseModel | "toJSON">> & {
         id?: string;
@@ -758,6 +779,20 @@ interface QueryResponse {
 interface SaveResponse {
     success: boolean;
     id: string;
+    /**
+     * Server-applied field values the DO wrote AFTER the caller's submission
+     * inputs were assembled, read back from the final post-hook `data`
+     * (#1476, consolidating the #1462 `stamps` channel). This is the single
+     * "server-applied fields" channel: it carries both the applied `autoStamps`
+     * timestamps and any fields a `beforeSave` hook reported via
+     * `serverAppliedFieldNames` (e.g. app-level trigger-computed values). Present
+     * only when at least one such field ended up with a value. Lets the Worker
+     * thread these values into the change-event `data` it broadcasts to
+     * subscribers — otherwise a `select`-listed stamped or trigger-computed field
+     * never reaches the frame, because the frame is rebuilt from the submission
+     * inputs (which predate the DO-side write).
+     */
+    appliedFields?: Record<string, any>;
 }
 interface DeleteResponse {
     success: boolean;
@@ -814,6 +849,8 @@ interface PatchRequest {
 interface PatchResponse {
     success: boolean;
     id: string;
+    /** Server-applied field values (#1476). See `SaveResponse.appliedFields`. */
+    appliedFields?: Record<string, any>;
 }
 interface BatchOperation {
     op: "save" | "patch" | "delete" | "increment" | "addToSet" | "removeFromSet";
@@ -841,12 +878,46 @@ interface BatchOperation {
 }
 interface BatchRequest {
     operations: BatchOperation[];
+    /**
+     * All-or-nothing execution (#1478). When `true`, the FIRST operation that
+     * fails inside the transaction — hook denial, condition / `ifNotExists` /
+     * unique violation, record-not-found, or upsert validation error — aborts
+     * the whole batch: every write is rolled back and the handler returns an
+     * error naming the failed step with its natural HTTP status (see
+     * `BatchOperationResult.status`). When `false` or absent (the default), each
+     * operation's outcome is recorded independently and successful siblings
+     * commit — the partial-success behavior import-bulk and applyToQuery rely on.
+     */
+    atomic?: boolean;
 }
+/**
+ * Stable, machine-readable failure tag on a failed `BatchOperationResult`
+ * (#1478). Derived at each failure site — never inferred from the `error`
+ * string. `#1389` (conditional writes + fencing-token enforcement) surfaces its
+ * condition / stale-token rejections through this same channel.
+ */
+type BatchFailureCode = "NOT_FOUND" | "HOOK_DENIED" | "CONDITION_NOT_MET" | "ALREADY_EXISTS" | "UNIQUE_VIOLATION" | "VALIDATION_ERROR";
 interface BatchOperationResult {
     success: boolean;
     id: string;
     error?: string;
+    /**
+     * Structured failure metadata (#1478), present only on a failed result. Both
+     * are derived at the failure site, not parsed back out of `error`:
+     *  - `status` — the natural HTTP status for the cause (404 not found,
+     *    403 hook denial, 409 condition / `ifNotExists` / unique conflict,
+     *    400 upsert validation).
+     *  - `code` — a stable machine-readable tag (see `BatchFailureCode`).
+     *
+     * In atomic mode the handler reads the first failure's `status`/`code` to
+     * build the error response, so an increment-on-missing op keeps its 404 and a
+     * hook denial keeps its 403 instead of collapsing to a uniform 409.
+     */
+    status?: number;
+    code?: BatchFailureCode;
     values?: Record<string, number>;
+    /** Server-applied field values (#1476). See `SaveResponse.appliedFields`. */
+    appliedFields?: Record<string, any>;
 }
 interface BatchResponse {
     results: BatchOperationResult[];

package/dist/client.d.ts

@@ -563,6 +563,27 @@ declare class BaseModel implements StringSetChangeTracker {
      */
     static count(this: new (...args: any[]) => any, filter?: DocumentFilter, options?: Pick<QueryOptions, "documents">): Promise<number>;
     static findAll<T extends BaseModel>(this: new (...args: any[]) => T): Promise<T[]>;
+    /**
+     * Resolve a record by its unique-constraint field values via an engine query.
+     * Used as a fallback when the `_uniqueIdx_<model>_<constraint>` map has no
+     * entry for a key.
+     *
+     * The index map is a cache over the SQLite projection, not the source of
+     * truth: every record is loaded into the projection on `initializeForDocument`
+     * regardless of index presence, but a record written by a client predating
+     * index maintenance (legacy data) is missing from the index. Such a record
+     * silently escapes both `upsertByUnique` lookups and the `save()` uniqueness
+     * check. A query over the constraint fields finds it reliably.
+     *
+     * Contract: RESOLVE ONLY. Returns the owning record (with `_metaDocId` set to
+     * the document that holds it, via `queryOne`) or `null`. Callers decide
+     * whether to heal the missing index entry (write paths) and do their own
+     * logging — this method never mutates the index, so read paths stay
+     * read-only. Mirrors `buildUniqueKey`: a null/undefined value in any
+     * constraint field means the record does not participate in the constraint,
+     * so no query runs.
+     */
+    private static _resolveByUniqueFallback;
     static findByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, value: any | any[]): Promise<T | null>;
     static upsertByUnique<T extends BaseModel>(this: typeof BaseModel & (new (...args: any[]) => T), constraintName: string, uniqueLookupValue: any | any[], dataToUpsert: Partial<Omit<InstanceType<new (...args: any[]) => T>, keyof BaseModel | "toJSON">> & {
         id?: string;
@@ -758,6 +779,20 @@ interface QueryResponse {
 interface SaveResponse {
     success: boolean;
     id: string;
+    /**
+     * Server-applied field values the DO wrote AFTER the caller's submission
+     * inputs were assembled, read back from the final post-hook `data`
+     * (#1476, consolidating the #1462 `stamps` channel). This is the single
+     * "server-applied fields" channel: it carries both the applied `autoStamps`
+     * timestamps and any fields a `beforeSave` hook reported via
+     * `serverAppliedFieldNames` (e.g. app-level trigger-computed values). Present
+     * only when at least one such field ended up with a value. Lets the Worker
+     * thread these values into the change-event `data` it broadcasts to
+     * subscribers — otherwise a `select`-listed stamped or trigger-computed field
+     * never reaches the frame, because the frame is rebuilt from the submission
+     * inputs (which predate the DO-side write).
+     */
+    appliedFields?: Record<string, any>;
 }
 interface DeleteResponse {
     success: boolean;
@@ -814,6 +849,8 @@ interface PatchRequest {
 interface PatchResponse {
     success: boolean;
     id: string;
+    /** Server-applied field values (#1476). See `SaveResponse.appliedFields`. */
+    appliedFields?: Record<string, any>;
 }
 interface BatchOperation {
     op: "save" | "patch" | "delete" | "increment" | "addToSet" | "removeFromSet";
@@ -841,12 +878,46 @@ interface BatchOperation {
 }
 interface BatchRequest {
     operations: BatchOperation[];
+    /**
+     * All-or-nothing execution (#1478). When `true`, the FIRST operation that
+     * fails inside the transaction — hook denial, condition / `ifNotExists` /
+     * unique violation, record-not-found, or upsert validation error — aborts
+     * the whole batch: every write is rolled back and the handler returns an
+     * error naming the failed step with its natural HTTP status (see
+     * `BatchOperationResult.status`). When `false` or absent (the default), each
+     * operation's outcome is recorded independently and successful siblings
+     * commit — the partial-success behavior import-bulk and applyToQuery rely on.
+     */
+    atomic?: boolean;
 }
+/**
+ * Stable, machine-readable failure tag on a failed `BatchOperationResult`
+ * (#1478). Derived at each failure site — never inferred from the `error`
+ * string. `#1389` (conditional writes + fencing-token enforcement) surfaces its
+ * condition / stale-token rejections through this same channel.
+ */
+type BatchFailureCode = "NOT_FOUND" | "HOOK_DENIED" | "CONDITION_NOT_MET" | "ALREADY_EXISTS" | "UNIQUE_VIOLATION" | "VALIDATION_ERROR";
 interface BatchOperationResult {
     success: boolean;
     id: string;
     error?: string;
+    /**
+     * Structured failure metadata (#1478), present only on a failed result. Both
+     * are derived at the failure site, not parsed back out of `error`:
+     *  - `status` — the natural HTTP status for the cause (404 not found,
+     *    403 hook denial, 409 condition / `ifNotExists` / unique conflict,
+     *    400 upsert validation).
+     *  - `code` — a stable machine-readable tag (see `BatchFailureCode`).
+     *
+     * In atomic mode the handler reads the first failure's `status`/`code` to
+     * build the error response, so an increment-on-missing op keeps its 404 and a
+     * hook denial keeps its 403 instead of collapsing to a uniform 409.
+     */
+    status?: number;
+    code?: BatchFailureCode;
     values?: Record<string, number>;
+    /** Server-applied field values (#1476). See `SaveResponse.appliedFields`. */
+    appliedFields?: Record<string, any>;
 }
 interface BatchResponse {
     results: BatchOperationResult[];

package/dist/client.js

@@ -65,8 +65,32 @@ var init_yjsValues = __esm({
   }
 });
 
-// src/models/metaSync.ts
+// src/models/writeLifecycle.ts
 import * as Y2 from "yjs";
+import { ulid } from "ulid";
+function registerFunctionDefaultGenerator(name, fn) {
+  FUNCTION_DEFAULT_GENERATORS.set(name, fn);
+}
+var KNOWN_FIELD_TYPE_MAP, KNOWN_FIELD_TYPES, FUNCTION_DEFAULT_GENERATORS;
+var init_writeLifecycle = __esm({
+  "src/models/writeLifecycle.ts"() {
+    "use strict";
+    KNOWN_FIELD_TYPE_MAP = {
+      string: true,
+      number: true,
+      boolean: true,
+      date: true,
+      id: true,
+      stringset: true
+    };
+    KNOWN_FIELD_TYPES = new Set(Object.keys(KNOWN_FIELD_TYPE_MAP));
+    FUNCTION_DEFAULT_GENERATORS = /* @__PURE__ */ new Map();
+    registerFunctionDefaultGenerator("generate_ulid", () => ulid());
+  }
+});
+
+// src/models/metaSync.ts
+import * as Y3 from "yjs";
 function registerFunctionDefault(fn, name) {
   KNOWN_FUNCTION_DEFAULTS.set(fn, name);
 }
@@ -75,15 +99,24 @@ var init_metaSync = __esm({
   "src/models/metaSync.ts"() {
     "use strict";
     init_yjsValues();
+    init_writeLifecycle();
     KNOWN_FUNCTION_DEFAULTS = /* @__PURE__ */ new WeakMap();
   }
 });
 
+// src/utils/uniqueIndex.ts
+import * as Y4 from "yjs";
+var init_uniqueIndex = __esm({
+  "src/utils/uniqueIndex.ts"() {
+    "use strict";
+  }
+});
+
 // src/models/BaseModel.ts
-import * as Y3 from "yjs";
-import { ulid } from "ulid";
+import * as Y5 from "yjs";
+import { ulid as ulid2 } from "ulid";
 function generateULID() {
-  return ulid();
+  return ulid2();
 }
 var Logger;
 var init_BaseModel = __esm({
@@ -95,7 +128,9 @@ var init_BaseModel = __esm({
     init_CursorManager();
     init_sql();
     init_metaSync();
+    init_writeLifecycle();
     init_yjsValues();
+    init_uniqueIndex();
     Logger = class {
       static _logLevel = 1 /* ERROR */;
       static _logCallback = null;