js-bao 0.5.0 → 0.5.2

package/dist/index.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;
@@ -529,6 +553,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;
@@ -663,6 +698,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;
@@ -835,6 +891,11 @@ declare function attachAndRegisterModel(modelClass: typeof BaseModel, schema: De
 
 /**
  * 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;
 /**
@@ -919,6 +980,7 @@ interface DiscoveredField {
     required?: boolean;
     default?: string | number | boolean;
     autoAssign?: boolean;
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
 }
@@ -961,6 +1023,41 @@ declare function discoverModelNames(yDoc: Y.Doc): string[];
  */
 declare function schemaToToml(schema: DiscoveredSchema): string;
 
+/**
+ * Unique-constraint index helpers (shared CRDT contract).
+ *
+ * js-bao enforces unique constraints inside the Yjs document, not via a SQL
+ * `UNIQUE`. Each constraint has a `_uniqueIdx_<model>_<constraint>` map
+ * (uniqueKey -> surviving recordId) and a document observer that
+ * deterministically discards duplicate losers. Both the client write path and
+ * the server-direct write path (`mutateRecord` in js-bao-wss) must derive the
+ * key and the index map name the SAME way, or a server-written record would
+ * not be seen by the client-side resolver. These helpers are the single source
+ * of truth for that derivation so neither side keeps a parallel copy.
+ */
+
+/**
+ * Build the unique-constraint key for a record over the given fields.
+ *
+ * Mirrors the document-observer conflict resolver: a `null`/`undefined` value
+ * in any field means the record does not participate in the constraint (returns
+ * `null`); otherwise the per-field `String()` values joined by `"|"`. This is
+ * the key the `_uniqueIdx_*` map is read/written with during conflict
+ * resolution, so it is the key the resolver treats as authoritative.
+ */
+declare function buildUniqueKey(recordData: Y.Map<any> | Record<string, any>, fields: string[]): string | null;
+/**
+ * Name of the Yjs map that indexes a unique constraint within a document:
+ * `_uniqueIdx_<model>_<constraint>` mapping uniqueKey -> surviving recordId.
+ */
+declare function uniqueIndexMapName(modelName: string, constraintName: string): string;
+/**
+ * The constraint name js-bao assigns to a single-field `unique: true` field
+ * (see `resolveUniqueConstraints` in models/schema.ts). Compound constraints
+ * keep their author-given name instead.
+ */
+declare function fieldUniqueConstraintName(modelName: string, fieldName: string): string;
+
 interface DumpOptions {
     includeIndexes?: boolean;
 }
@@ -997,4 +1094,4 @@ declare function dumpYDocToPlain(yDoc: Y.Doc, options?: DumpOptions): PlainYDoc;
  */
 declare function summarizePlainYDoc(dump: PlainYDoc): DumpSummary;
 
-export { BaseModel, type ConnectedDocument, type DatabaseConfig, DatabaseEngine, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, DocumentClosedError, type DocumentConnectionCallback, type DocumentConnectionEvent, type DocumentFilter, type DocumentManager, type DocumentPermissionHint, DocumentResolutionError, type DumpOptions, type DumpSummary, type DumpSummaryEntry, type FieldOptions, type IncludeSpec, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, type ModelConstructor, type ModelOptions, ModelRegistry, type PaginatedResult, type PaginationOptions, type PlainYDoc, type ProjectionSpec, type QueryOptions, type QueryResult, RecordNotFoundError, type SaveOptions, StringSet, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, clearMetaSyncCache, createModelClass, defineModelSchema, discoverModelNames, discoverSchema, dumpYDocToPlain, generateULID, inferFieldType, initJsBao, loadSchemaFromToml, loadSchemaFromTomlString, registerFunctionDefault, resetJsBao, schemaToToml, summarizePlainYDoc, syncInferredMeta, syncModelMeta };
+export { BaseModel, type ConnectedDocument, type DatabaseConfig, DatabaseEngine, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, DocumentClosedError, type DocumentConnectionCallback, type DocumentConnectionEvent, type DocumentFilter, type DocumentManager, type DocumentPermissionHint, DocumentResolutionError, type DumpOptions, type DumpSummary, type DumpSummaryEntry, type FieldOptions, type IncludeSpec, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, type ModelConstructor, type ModelOptions, ModelRegistry, type PaginatedResult, type PaginationOptions, type PlainYDoc, type ProjectionSpec, type QueryOptions, type QueryResult, RecordNotFoundError, type SaveOptions, StringSet, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, buildUniqueKey, clearMetaSyncCache, createModelClass, defineModelSchema, discoverModelNames, discoverSchema, dumpYDocToPlain, fieldUniqueConstraintName, generateULID, inferFieldType, initJsBao, loadSchemaFromToml, loadSchemaFromTomlString, registerFunctionDefault, resetJsBao, schemaToToml, summarizePlainYDoc, syncInferredMeta, syncModelMeta, uniqueIndexMapName };

package/dist/index.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;
@@ -529,6 +553,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;
@@ -663,6 +698,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;
@@ -835,6 +891,11 @@ declare function attachAndRegisterModel(modelClass: typeof BaseModel, schema: De
 
 /**
  * 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;
 /**
@@ -919,6 +980,7 @@ interface DiscoveredField {
     required?: boolean;
     default?: string | number | boolean;
     autoAssign?: boolean;
+    autoStamp?: "create" | "update" | "both";
     maxLength?: number;
     maxCount?: number;
 }
@@ -961,6 +1023,41 @@ declare function discoverModelNames(yDoc: Y.Doc): string[];
  */
 declare function schemaToToml(schema: DiscoveredSchema): string;
 
+/**
+ * Unique-constraint index helpers (shared CRDT contract).
+ *
+ * js-bao enforces unique constraints inside the Yjs document, not via a SQL
+ * `UNIQUE`. Each constraint has a `_uniqueIdx_<model>_<constraint>` map
+ * (uniqueKey -> surviving recordId) and a document observer that
+ * deterministically discards duplicate losers. Both the client write path and
+ * the server-direct write path (`mutateRecord` in js-bao-wss) must derive the
+ * key and the index map name the SAME way, or a server-written record would
+ * not be seen by the client-side resolver. These helpers are the single source
+ * of truth for that derivation so neither side keeps a parallel copy.
+ */
+
+/**
+ * Build the unique-constraint key for a record over the given fields.
+ *
+ * Mirrors the document-observer conflict resolver: a `null`/`undefined` value
+ * in any field means the record does not participate in the constraint (returns
+ * `null`); otherwise the per-field `String()` values joined by `"|"`. This is
+ * the key the `_uniqueIdx_*` map is read/written with during conflict
+ * resolution, so it is the key the resolver treats as authoritative.
+ */
+declare function buildUniqueKey(recordData: Y.Map<any> | Record<string, any>, fields: string[]): string | null;
+/**
+ * Name of the Yjs map that indexes a unique constraint within a document:
+ * `_uniqueIdx_<model>_<constraint>` mapping uniqueKey -> surviving recordId.
+ */
+declare function uniqueIndexMapName(modelName: string, constraintName: string): string;
+/**
+ * The constraint name js-bao assigns to a single-field `unique: true` field
+ * (see `resolveUniqueConstraints` in models/schema.ts). Compound constraints
+ * keep their author-given name instead.
+ */
+declare function fieldUniqueConstraintName(modelName: string, fieldName: string): string;
+
 interface DumpOptions {
     includeIndexes?: boolean;
 }
@@ -997,4 +1094,4 @@ declare function dumpYDocToPlain(yDoc: Y.Doc, options?: DumpOptions): PlainYDoc;
  */
 declare function summarizePlainYDoc(dump: PlainYDoc): DumpSummary;
 
-export { BaseModel, type ConnectedDocument, type DatabaseConfig, DatabaseEngine, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, DocumentClosedError, type DocumentConnectionCallback, type DocumentConnectionEvent, type DocumentFilter, type DocumentManager, type DocumentPermissionHint, DocumentResolutionError, type DumpOptions, type DumpSummary, type DumpSummaryEntry, type FieldOptions, type IncludeSpec, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, type ModelConstructor, type ModelOptions, ModelRegistry, type PaginatedResult, type PaginationOptions, type PlainYDoc, type ProjectionSpec, type QueryOptions, type QueryResult, RecordNotFoundError, type SaveOptions, StringSet, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, clearMetaSyncCache, createModelClass, defineModelSchema, discoverModelNames, discoverSchema, dumpYDocToPlain, generateULID, inferFieldType, initJsBao, loadSchemaFromToml, loadSchemaFromTomlString, registerFunctionDefault, resetJsBao, schemaToToml, summarizePlainYDoc, syncInferredMeta, syncModelMeta };
+export { BaseModel, type ConnectedDocument, type DatabaseConfig, DatabaseEngine, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, DocumentClosedError, type DocumentConnectionCallback, type DocumentConnectionEvent, type DocumentFilter, type DocumentManager, type DocumentPermissionHint, DocumentResolutionError, type DumpOptions, type DumpSummary, type DumpSummaryEntry, type FieldOptions, type IncludeSpec, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, type ModelConstructor, type ModelOptions, ModelRegistry, type PaginatedResult, type PaginationOptions, type PlainYDoc, type ProjectionSpec, type QueryOptions, type QueryResult, RecordNotFoundError, type SaveOptions, StringSet, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, buildUniqueKey, clearMetaSyncCache, createModelClass, defineModelSchema, discoverModelNames, discoverSchema, dumpYDocToPlain, fieldUniqueConstraintName, generateULID, inferFieldType, initJsBao, loadSchemaFromToml, loadSchemaFromTomlString, registerFunctionDefault, resetJsBao, schemaToToml, summarizePlainYDoc, syncInferredMeta, syncModelMeta, uniqueIndexMapName };