js-bao 0.5.0 → 0.5.1

package/dist/cloudflare.cjs

@@ -84,9 +84,25 @@ var init_DocumentQueryTranslator = __esm({
   }
 });
 
+// src/utils/yjsValues.ts
+function isStringSetYMap(value) {
+  if (!(value instanceof Y.Map)) return false;
+  for (const v of value.values()) {
+    if (v !== true) return false;
+  }
+  return true;
+}
+var Y;
+var init_yjsValues = __esm({
+  "src/utils/yjsValues.ts"() {
+    "use strict";
+    Y = __toESM(require("yjs"), 1);
+  }
+});
+
 // src/models/metaSync.ts
 function inferFieldType(value) {
-  if (value instanceof Y.Map) return "stringset";
+  if (isStringSetYMap(value)) return "stringset";
   switch (typeof value) {
     case "string":
       return "string";
@@ -131,7 +147,7 @@ function syncModelMeta(yDoc, modelName, schema) {
   if (compoundConstraints.length > 0) {
     let constraints = meta.get("_constraints");
     if (!constraints) {
-      constraints = new Y.Map();
+      constraints = new Y2.Map();
       meta.set("_constraints", constraints);
     }
     for (const constraint of compoundConstraints) {
@@ -142,7 +158,7 @@ function syncModelMeta(yDoc, modelName, schema) {
   if (relationships && Object.keys(relationships).length > 0) {
     let rels = meta.get("_relationships");
     if (!rels) {
-      rels = new Y.Map();
+      rels = new Y2.Map();
       meta.set("_relationships", rels);
     }
     for (const [relName, relConfig] of Object.entries(relationships)) {
@@ -154,7 +170,7 @@ function syncModelMeta(yDoc, modelName, schema) {
 function syncFieldMeta(metaMap, fieldName, fieldOpts) {
   let fieldMeta = metaMap.get(fieldName);
   if (!fieldMeta) {
-    fieldMeta = new Y.Map();
+    fieldMeta = new Y2.Map();
     metaMap.set(fieldName, fieldMeta);
   }
   setIfChanged(fieldMeta, "type", fieldOpts.type);
@@ -162,6 +178,7 @@ function syncFieldMeta(metaMap, fieldName, fieldOpts) {
   if (fieldOpts.unique) setIfChanged(fieldMeta, "unique", true);
   if (fieldOpts.required) setIfChanged(fieldMeta, "required", true);
   if (fieldOpts.autoAssign) setIfChanged(fieldMeta, "autoAssign", true);
+  if (fieldOpts.autoStamp) setIfChanged(fieldMeta, "autoStamp", fieldOpts.autoStamp);
   if (fieldOpts.maxLength !== void 0) setIfChanged(fieldMeta, "maxLength", fieldOpts.maxLength);
   if (fieldOpts.maxCount !== void 0) setIfChanged(fieldMeta, "maxCount", fieldOpts.maxCount);
   const encoded = encodeDefault(fieldOpts.default);
@@ -170,7 +187,7 @@ function syncFieldMeta(metaMap, fieldName, fieldOpts) {
 function syncConstraintMeta(constraintsMap, constraint) {
   let cMeta = constraintsMap.get(constraint.name);
   if (!cMeta) {
-    cMeta = new Y.Map();
+    cMeta = new Y2.Map();
     constraintsMap.set(constraint.name, cMeta);
   }
   setIfChanged(cMeta, "type", "unique");
@@ -180,7 +197,7 @@ function syncConstraintMeta(constraintsMap, constraint) {
 function syncRelationshipMeta(relsMap, relName, relConfig) {
   let relMeta = relsMap.get(relName);
   if (!relMeta) {
-    relMeta = new Y.Map();
+    relMeta = new Y2.Map();
     relsMap.set(relName, relMeta);
   }
   for (const [key, value] of Object.entries(relConfig)) {
@@ -195,7 +212,7 @@ function syncInferredMeta(yDoc, modelName, recordData) {
     if (fieldName.startsWith("_")) continue;
     let fieldMeta = meta.get(fieldName);
     if (!fieldMeta) {
-      fieldMeta = new Y.Map();
+      fieldMeta = new Y2.Map();
       meta.set(fieldName, fieldMeta);
     }
     if (!fieldMeta.has("type")) {
@@ -211,11 +228,12 @@ function setIfChanged(map, key, value) {
     map.set(key, value);
   }
 }
-var Y, KNOWN_FUNCTION_DEFAULTS, _syncedCache;
+var Y2, KNOWN_FUNCTION_DEFAULTS, _syncedCache;
 var init_metaSync = __esm({
   "src/models/metaSync.ts"() {
     "use strict";
-    Y = __toESM(require("yjs"), 1);
+    Y2 = __toESM(require("yjs"), 1);
+    init_yjsValues();
     KNOWN_FUNCTION_DEFAULTS = /* @__PURE__ */ new WeakMap();
     _syncedCache = /* @__PURE__ */ new WeakMap();
   }
@@ -225,11 +243,11 @@ var init_metaSync = __esm({
 function generateULID() {
   return (0, import_ulid.ulid)();
 }
-var Y2, import_ulid, Logger;
+var Y3, import_ulid, Logger;
 var init_BaseModel = __esm({
   "src/models/BaseModel.ts"() {
     "use strict";
-    Y2 = __toESM(require("yjs"), 1);
+    Y3 = __toESM(require("yjs"), 1);
     import_ulid = require("ulid");
     init_StringSet();
     init_documentTypes();
@@ -237,6 +255,7 @@ var init_BaseModel = __esm({
     init_CursorManager();
     init_sql();
     init_metaSync();
+    init_yjsValues();
     Logger = class {
       static _logLevel = 1 /* ERROR */;
       static _logCallback = null;
@@ -1223,7 +1242,8 @@ function connectDoDb(options) {
 }
 
 // src/utils/yDocSchema.ts
-var Y3 = __toESM(require("yjs"), 1);
+var Y4 = __toESM(require("yjs"), 1);
+init_yjsValues();
 function discoverSchema(yDoc) {
   const models = {};
   const metaNames = /* @__PURE__ */ new Set();
@@ -1257,7 +1277,7 @@ function discoverModelNames(yDoc) {
 function materializeMap(yDoc, key) {
   try {
     const map = yDoc.getMap(key);
-    return map instanceof Y3.Map ? map : null;
+    return map instanceof Y4.Map ? map : null;
   } catch {
     return null;
   }
@@ -1267,11 +1287,11 @@ function readModelMeta(metaMap) {
   let constraints;
   let relationships;
   for (const [key, value] of metaMap.entries()) {
-    if (key === "_constraints" && value instanceof Y3.Map) {
+    if (key === "_constraints" && value instanceof Y4.Map) {
       constraints = readConstraints(value);
-    } else if (key === "_relationships" && value instanceof Y3.Map) {
+    } else if (key === "_relationships" && value instanceof Y4.Map) {
       relationships = readRelationships(value);
-    } else if (value instanceof Y3.Map) {
+    } else if (value instanceof Y4.Map) {
       fields[key] = readFieldMeta(value);
     }
   }
@@ -1290,6 +1310,10 @@ function readFieldMeta(fieldMap) {
   if (fieldMap.get("unique") === true) field.unique = true;
   if (fieldMap.get("required") === true) field.required = true;
   if (fieldMap.get("autoAssign") === true) field.autoAssign = true;
+  const autoStamp = fieldMap.get("autoStamp");
+  if (typeof autoStamp === "string" && (autoStamp === "create" || autoStamp === "update" || autoStamp === "both")) {
+    field.autoStamp = autoStamp;
+  }
   const def = fieldMap.get("default");
   if (def !== void 0) field.default = def;
   const maxLength = fieldMap.get("maxLength");
@@ -1302,7 +1326,7 @@ function inferModelFromData(dataMap) {
   const fields = {};
   let sampled = 0;
   for (const [_recordId, recordValue] of dataMap.entries()) {
-    if (!(recordValue instanceof Y3.Map)) continue;
+    if (!(recordValue instanceof Y4.Map)) continue;
     if (++sampled > 5) break;
     for (const [fieldName, value] of recordValue.entries()) {
       if (fieldName.startsWith("_")) continue;
@@ -1315,7 +1339,7 @@ function inferModelFromData(dataMap) {
   return { fields };
 }
 function inferTypeFromValue(value) {
-  if (value instanceof Y3.Map) return "stringset";
+  if (isStringSetYMap(value)) return "stringset";
   switch (typeof value) {
     case "string":
       return "string";
@@ -1330,7 +1354,7 @@ function inferTypeFromValue(value) {
 function readConstraints(constraintsMap) {
   const out = {};
   for (const [name, value] of constraintsMap.entries()) {
-    if (!(value instanceof Y3.Map)) continue;
+    if (!(value instanceof Y4.Map)) continue;
     let fields = [];
     const rawFields = value.get("fields");
     if (typeof rawFields === "string") {
@@ -1349,7 +1373,7 @@ function readConstraints(constraintsMap) {
 function readRelationships(relsMap) {
   const out = {};
   for (const [name, value] of relsMap.entries()) {
-    if (!(value instanceof Y3.Map)) continue;
+    if (!(value instanceof Y4.Map)) continue;
     const rel = {};
     for (const [k, v] of value.entries()) {
       rel[k] = v;
@@ -1360,6 +1384,7 @@ function readRelationships(relsMap) {
 }
 var CAMEL_TO_SNAKE = {
   autoAssign: "auto_assign",
+  autoStamp: "auto_stamp",
   maxLength: "max_length",
   maxCount: "max_count",
   relatedIdField: "related_id_field",
@@ -1390,6 +1415,7 @@ function schemaToToml(schema) {
       lines.push(`[models.${modelName}.fields.${fieldName}]`);
       lines.push(`type = ${tomlValue(field.type)}`);
       if (field.autoAssign) lines.push("auto_assign = true");
+      if (field.autoStamp) lines.push(`auto_stamp = ${tomlValue(field.autoStamp)}`);
       if (field.indexed) lines.push("indexed = true");
       if (field.unique) lines.push("unique = true");
       if (field.required) lines.push("required = true");
@@ -1513,10 +1539,13 @@ var KNOWN_FIELD_KEYS = /* @__PURE__ */ new Set([
   "unique",
   "required",
   "auto_assign",
+  "auto_stamp",
   "max_length",
   "max_count",
-  "default"
+  "default",
+  "enum"
 ]);
+var VALID_AUTO_STAMP_VALUES = /* @__PURE__ */ new Set(["create", "update", "both"]);
 var KNOWN_MODEL_KEYS = /* @__PURE__ */ new Set([
   "fields",
   "relationships",
@@ -1558,9 +1587,37 @@ function parseFieldOptions(raw, context, strict) {
   if (raw.unique === true) opts.unique = true;
   if (raw.required === true) opts.required = true;
   if (raw.auto_assign === true) opts.autoAssign = true;
+  if (raw.auto_stamp !== void 0) {
+    if (typeof raw.auto_stamp !== "string" || !VALID_AUTO_STAMP_VALUES.has(raw.auto_stamp)) {
+      throw new Error(
+        `${context}: invalid auto_stamp value "${raw.auto_stamp}". Must be one of: ${[
+          ...VALID_AUTO_STAMP_VALUES
+        ].join(", ")}`
+      );
+    }
+    opts.autoStamp = raw.auto_stamp;
+  }
   if (raw.max_length !== void 0) opts.maxLength = raw.max_length;
   if (raw.max_count !== void 0) opts.maxCount = raw.max_count;
   if (raw.default !== void 0) opts.default = raw.default;
+  if (raw.enum !== void 0) {
+    if (raw.type !== "string") {
+      throw new Error(
+        `${context}: \`enum\` is only valid on a "string" field, not "${raw.type}".`
+      );
+    }
+    if (!Array.isArray(raw.enum) || raw.enum.length === 0) {
+      throw new Error(
+        `${context}: \`enum\` must be a non-empty array of strings.`
+      );
+    }
+    if (!raw.enum.every((v) => typeof v === "string")) {
+      throw new Error(
+        `${context}: \`enum\` values must all be strings.`
+      );
+    }
+    opts.enum = [...raw.enum];
+  }
   return opts;
 }
 function requireField(raw, field, context) {

package/dist/cloudflare.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;
@@ -754,6 +789,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;
@@ -862,6 +916,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;
@@ -877,6 +942,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[];
@@ -1435,6 +1513,7 @@ interface DiscoveredField {
     required?: boolean;
     default?: string | number | boolean;
     autoAssign?: boolean;
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
 }
@@ -1541,6 +1620,11 @@ declare function loadSchemaFromTomlString(tomlString: string, options?: LoadSche
 
 /**
  * Infer a _meta_ type string from a JS runtime value.
+ *
+ * Only an all-`true` Y.Map (the stringset wire shape) is tagged as
+ * `stringset` (issue #625) — a Y.Map carrying a composite payload, or a
+ * Y.Array / Y.Text, is not a stringset and stays untyped (`null`) rather
+ * than being mis-tagged.
  */
 declare function inferFieldType(value: unknown): "string" | "number" | "boolean" | "stringset" | null;
 /**

package/dist/cloudflare.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;
@@ -754,6 +789,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;
@@ -862,6 +916,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;
@@ -877,6 +942,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[];
@@ -1435,6 +1513,7 @@ interface DiscoveredField {
     required?: boolean;
     default?: string | number | boolean;
     autoAssign?: boolean;
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
 }
@@ -1541,6 +1620,11 @@ declare function loadSchemaFromTomlString(tomlString: string, options?: LoadSche
 
 /**
  * Infer a _meta_ type string from a JS runtime value.
+ *
+ * Only an all-`true` Y.Map (the stringset wire shape) is tagged as
+ * `stringset` (issue #625) — a Y.Map carrying a composite payload, or a
+ * Y.Array / Y.Text, is not a stringset and stays untyped (`null`) rather
+ * than being mis-tagged.
  */
 declare function inferFieldType(value: unknown): "string" | "number" | "boolean" | "stringset" | null;
 /**