js-bao 0.5.0 → 0.5.1

package/dist/client.d.cts

@@ -31,8 +31,32 @@ interface FieldOptions {
     unique?: boolean;
     default?: any | (() => any);
     autoAssign?: boolean;
+    /**
+     * Auto-timestamp this field with `Date.now()` (milliseconds) on save.
+     *
+     * - `'create'` — stamp only on the first save (when `isNew === true`).
+     * - `'update'` — stamp on every save (create AND update).
+     * - `'both'`   — stamp on every save (create AND update).
+     *
+     * If the caller passes an explicit value for the field in `data`, the
+     * explicit value wins and the stamp is skipped. The stamp is applied
+     * in `beforeSave` BEFORE any user-defined hooks, so user hooks may
+     * still overwrite the value if they wish (last writer wins).
+     */
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
+    /**
+     * Allowed-value set for a `string` field. When present, the codegen
+     * generators (database-type codegen + doc-model v2 codegen) emit a
+     * TypeScript string-literal union (`"a" | "b" | "c"`) instead of a bare
+     * `string` for this field.
+     *
+     * Advisory / codegen-only: this is a TS-emission hint. The runtime and the
+     * server do NOT enforce enum membership on write (see #843). Only valid on
+     * `string` fields, and must be a non-empty array of strings.
+     */
+    enum?: string[];
 }
 interface UniqueConstraintConfig {
     name: string;
@@ -394,6 +418,17 @@ declare class BaseModel implements StringSetChangeTracker {
     private ensureLocalChanges;
     private hasLocalChange;
     private getFromYjs;
+    /**
+     * Defensive normalization for the read/sync boundary (issue #625).
+     *
+     * Stringset fields are owned by getStringSetFromYjs (which expects the
+     * raw Y.Map / legacy plain-object shape — #561 / #601), so they pass
+     * through untouched. For any other field, a composite Yjs primitive
+     * (Y.Map / Y.Array / Y.Text) must never reach user code or the DB layer
+     * raw: normalize it to its plain-JS projection (toJSON / toString) and
+     * warn, rather than throwing. Scalars pass through unchanged.
+     */
+    private normalizeNonStringSetValue;
     private getValue;
     private setValue;
     get isDirty(): boolean;
@@ -682,6 +717,25 @@ interface SaveRequest {
     ifNotExists?: boolean;
     condition?: DocumentFilter;
     upsertOn?: string;
+    /**
+     * Per-call auto-timestamp directives for schemaless writes.
+     *
+     * Each entry is a list of field names to stamp with `Date.now()`
+     * (milliseconds) at the corresponding lifecycle event:
+     *
+     * - `create` — field is stamped only when the record is new
+     *   (no row exists yet for this `modelName` + `id`).
+     * - `update` — field is stamped on every save (create AND update).
+     *
+     * If the caller already provided an explicit value for the field
+     * in `data`, the explicit value wins and the stamp is skipped.
+     * Stamping happens BEFORE the `beforeSave` user hook runs, so user
+     * hooks may still overwrite the stamped value if they wish.
+     */
+    autoStamps?: {
+        create?: string[];
+        update?: string[];
+    };
 }
 interface DeleteRequest {
     modelName: string;
@@ -745,6 +799,17 @@ interface PatchRequest {
     data: Record<string, any>;
     stringSets?: Record<string, string[]>;
     condition?: DocumentFilter;
+    /**
+     * Per-call auto-timestamp directives. A patch is always treated as
+     * an update (`isNew === false`), so only the `update` list is
+     * applied; the `create` list is ignored on patch.
+     *
+     * Explicit values in `data` win.
+     */
+    autoStamps?: {
+        create?: string[];
+        update?: string[];
+    };
 }
 interface PatchResponse {
     success: boolean;
@@ -760,6 +825,19 @@ interface BatchOperation {
     ifNotExists?: boolean;
     condition?: DocumentFilter;
     upsertOn?: string;
+    /**
+     * Per-operation auto-timestamp directives. Same semantics as
+     * `SaveRequest.autoStamps` / `PatchRequest.autoStamps`. Applied
+     * BEFORE the user `beforeSave` hook runs, with explicit values
+     * in `data` always winning.
+     *
+     * For `op: "patch"`, only the `update` list applies (patches are
+     * always treated as updates).
+     */
+    autoStamps?: {
+        create?: string[];
+        update?: string[];
+    };
 }
 interface BatchRequest {
     operations: BatchOperation[];

package/dist/client.d.ts

@@ -31,8 +31,32 @@ interface FieldOptions {
     unique?: boolean;
     default?: any | (() => any);
     autoAssign?: boolean;
+    /**
+     * Auto-timestamp this field with `Date.now()` (milliseconds) on save.
+     *
+     * - `'create'` — stamp only on the first save (when `isNew === true`).
+     * - `'update'` — stamp on every save (create AND update).
+     * - `'both'`   — stamp on every save (create AND update).
+     *
+     * If the caller passes an explicit value for the field in `data`, the
+     * explicit value wins and the stamp is skipped. The stamp is applied
+     * in `beforeSave` BEFORE any user-defined hooks, so user hooks may
+     * still overwrite the value if they wish (last writer wins).
+     */
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
+    /**
+     * Allowed-value set for a `string` field. When present, the codegen
+     * generators (database-type codegen + doc-model v2 codegen) emit a
+     * TypeScript string-literal union (`"a" | "b" | "c"`) instead of a bare
+     * `string` for this field.
+     *
+     * Advisory / codegen-only: this is a TS-emission hint. The runtime and the
+     * server do NOT enforce enum membership on write (see #843). Only valid on
+     * `string` fields, and must be a non-empty array of strings.
+     */
+    enum?: string[];
 }
 interface UniqueConstraintConfig {
     name: string;
@@ -394,6 +418,17 @@ declare class BaseModel implements StringSetChangeTracker {
     private ensureLocalChanges;
     private hasLocalChange;
     private getFromYjs;
+    /**
+     * Defensive normalization for the read/sync boundary (issue #625).
+     *
+     * Stringset fields are owned by getStringSetFromYjs (which expects the
+     * raw Y.Map / legacy plain-object shape — #561 / #601), so they pass
+     * through untouched. For any other field, a composite Yjs primitive
+     * (Y.Map / Y.Array / Y.Text) must never reach user code or the DB layer
+     * raw: normalize it to its plain-JS projection (toJSON / toString) and
+     * warn, rather than throwing. Scalars pass through unchanged.
+     */
+    private normalizeNonStringSetValue;
     private getValue;
     private setValue;
     get isDirty(): boolean;
@@ -682,6 +717,25 @@ interface SaveRequest {
     ifNotExists?: boolean;
     condition?: DocumentFilter;
     upsertOn?: string;
+    /**
+     * Per-call auto-timestamp directives for schemaless writes.
+     *
+     * Each entry is a list of field names to stamp with `Date.now()`
+     * (milliseconds) at the corresponding lifecycle event:
+     *
+     * - `create` — field is stamped only when the record is new
+     *   (no row exists yet for this `modelName` + `id`).
+     * - `update` — field is stamped on every save (create AND update).
+     *
+     * If the caller already provided an explicit value for the field
+     * in `data`, the explicit value wins and the stamp is skipped.
+     * Stamping happens BEFORE the `beforeSave` user hook runs, so user
+     * hooks may still overwrite the stamped value if they wish.
+     */
+    autoStamps?: {
+        create?: string[];
+        update?: string[];
+    };
 }
 interface DeleteRequest {
     modelName: string;
@@ -745,6 +799,17 @@ interface PatchRequest {
     data: Record<string, any>;
     stringSets?: Record<string, string[]>;
     condition?: DocumentFilter;
+    /**
+     * Per-call auto-timestamp directives. A patch is always treated as
+     * an update (`isNew === false`), so only the `update` list is
+     * applied; the `create` list is ignored on patch.
+     *
+     * Explicit values in `data` win.
+     */
+    autoStamps?: {
+        create?: string[];
+        update?: string[];
+    };
 }
 interface PatchResponse {
     success: boolean;
@@ -760,6 +825,19 @@ interface BatchOperation {
     ifNotExists?: boolean;
     condition?: DocumentFilter;
     upsertOn?: string;
+    /**
+     * Per-operation auto-timestamp directives. Same semantics as
+     * `SaveRequest.autoStamps` / `PatchRequest.autoStamps`. Applied
+     * BEFORE the user `beforeSave` hook runs, with explicit values
+     * in `data` always winning.
+     *
+     * For `op: "patch"`, only the `update` list applies (patches are
+     * always treated as updates).
+     */
+    autoStamps?: {
+        create?: string[];
+        update?: string[];
+    };
 }
 interface BatchRequest {
     operations: BatchOperation[];

package/dist/client.js

@@ -57,8 +57,16 @@ var init_DocumentQueryTranslator = __esm({
   }
 });
 
-// src/models/metaSync.ts
+// src/utils/yjsValues.ts
 import * as Y from "yjs";
+var init_yjsValues = __esm({
+  "src/utils/yjsValues.ts"() {
+    "use strict";
+  }
+});
+
+// src/models/metaSync.ts
+import * as Y2 from "yjs";
 function registerFunctionDefault(fn, name) {
   KNOWN_FUNCTION_DEFAULTS.set(fn, name);
 }
@@ -66,12 +74,13 @@ var KNOWN_FUNCTION_DEFAULTS;
 var init_metaSync = __esm({
   "src/models/metaSync.ts"() {
     "use strict";
+    init_yjsValues();
     KNOWN_FUNCTION_DEFAULTS = /* @__PURE__ */ new WeakMap();
   }
 });
 
 // src/models/BaseModel.ts
-import * as Y2 from "yjs";
+import * as Y3 from "yjs";
 import { ulid } from "ulid";
 function generateULID() {
   return ulid();
@@ -86,6 +95,7 @@ var init_BaseModel = __esm({
     init_CursorManager();
     init_sql();
     init_metaSync();
+    init_yjsValues();
     Logger = class {
       static _logLevel = 1 /* ERROR */;
       static _logCallback = null;