js-bao 0.5.1 → 0.5.2

package/dist/index.d.cts

@@ -698,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;
@@ -1002,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;
 }
@@ -1038,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

@@ -698,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;
@@ -1002,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;
 }
@@ -1038,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 };