js-bao 0.3.0 → 0.4.0

package/dist/cloudflare.d.cts

@@ -938,9 +938,10 @@ declare class DOClientEngine extends DatabaseEngine {
     /**
      * Save a record to the DO.
      */
-    saveModel(modelName: string, id: string, data: Record<string, any>, stringSets?: Record<string, string[]>, options?: {
+    saveModel(modelName: string, id: string | undefined, data: Record<string, any>, stringSets?: Record<string, string[]>, options?: {
         ifNotExists?: boolean;
         condition?: DocumentFilter;
+        upsertOn?: string;
     }): Promise<string>;
     /**
      * Patch (partial update) a record in the DO.
@@ -1297,6 +1298,7 @@ interface SaveOptions {
     stringSets?: Record<string, string[]>;
     ifNotExists?: boolean;
     condition?: DocumentFilter;
+    upsertOn?: string;
 }
 interface PatchOptions {
     stringSets?: Record<string, string[]>;
@@ -1383,4 +1385,147 @@ interface DoDb {
  */
 declare function connectDoDb(options: ConnectDoDbOptions): DoDb;
 
-export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation, type AggregationOptions, type AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type ConnectDoDbOptions, type CountRequest, type CountResponse, DOClientEngine, type DOClientEngineConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DoDb, type DocumentFilter, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, type ErrorResponse, type GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, type InitJsBaoDOOptions, type InitJsBaoDOResult, type ModelAccessor, type PaginatedResult, type PatchOptions, type PatchRequest, type PatchResponse, type ProjectionSpec, type QueryOptions, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveOptions, type SaveRequest, type SaveResponse, type SortSpec, type StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, type WriteCondition, connectDoDb, getActiveDOEngine, initJsBaoDO, resetJsBaoDO };
+/**
+ * YDoc Schema Discovery
+ *
+ * Reads _meta_* YMaps from a YDoc and returns a plain JSON description
+ * of the schema.  Works with any YDoc — no BaseModel or database needed.
+ *
+ * Usage:
+ *   import { discoverSchema } from "js-bao";
+ *   const schema = discoverSchema(yDoc);
+ */
+
+interface DiscoveredField {
+    type: string;
+    indexed?: boolean;
+    unique?: boolean;
+    required?: boolean;
+    default?: string | number | boolean;
+    autoAssign?: boolean;
+    maxLength?: number;
+    maxCount?: number;
+}
+interface DiscoveredConstraint {
+    type: string;
+    fields: string[];
+}
+interface DiscoveredRelationship {
+    type: string;
+    model: string;
+    [key: string]: any;
+}
+interface DiscoveredModel {
+    fields: Record<string, DiscoveredField>;
+    constraints?: Record<string, DiscoveredConstraint>;
+    relationships?: Record<string, DiscoveredRelationship>;
+}
+interface DiscoveredSchema {
+    models: Record<string, DiscoveredModel>;
+}
+/**
+ * Discover the schema embedded in a YDoc by reading its `_meta_*` maps.
+ *
+ * Returns a plain JSON object describing every model that has metadata.
+ * Does not require BaseModel, a database, or any schema registration —
+ * just a Y.Doc.
+ */
+declare function discoverSchema(yDoc: Y.Doc): DiscoveredSchema;
+/**
+ * List model names that have data in the YDoc (non-`_` prefixed top-level maps).
+ */
+declare function discoverModelNames(yDoc: Y.Doc): string[];
+/**
+ * Convert a DiscoveredSchema to a TOML string matching the js-bao
+ * schema format.
+ *
+ * Usage:
+ *   const schema = discoverSchema(yDoc);
+ *   const toml = schemaToToml(schema);
+ */
+declare function schemaToToml(schema: DiscoveredSchema): string;
+
+interface ResolvedUniqueConstraint {
+    name: string;
+    fields: string[];
+}
+interface ModelSchemaRuntimeShape {
+    class: typeof BaseModel;
+    options: ModelOptions;
+    fields: Map<string, FieldOptions>;
+    resolvedUniqueConstraints: ResolvedUniqueConstraint[];
+}
+interface DefinedModelSchema<TFields extends Record<string, FieldOptions> = Record<string, FieldOptions>> {
+    name: string;
+    fields: TFields;
+    options: ModelOptions;
+    runtimeShape?: ModelSchemaRuntimeShape;
+    buildRuntimeShape(modelClass: typeof BaseModel): ModelSchemaRuntimeShape;
+}
+
+/**
+ * TOML Schema Loader
+ *
+ * Parses a TOML schema file and returns an array of DefinedModelSchema
+ * objects.  Can be used in place of manual `defineModelSchema()` calls.
+ *
+ * TOML conventions:
+ *  - Property names are snake_case (auto_assign, max_count, …)
+ *  - Model names and field names are as-is (user-chosen)
+ *  - Relationships live under [models.*.relationships.*]
+ *  - Compound unique constraints are [[models.*.unique_constraints]]
+ */
+
+/**
+ * Parse a TOML string and return an array of DefinedModelSchema objects.
+ */
+declare function loadSchemaFromTomlString(tomlString: string): DefinedModelSchema[];
+
+/**
+ * Meta Sync — writes _meta_* YMaps into a YDoc.
+ *
+ * Each model with data in a YDoc gets a `_meta_{modelName}` YMap that
+ * describes the model's fields, constraints, and relationships.  This
+ * lets any language that can read a YDoc discover the schema without
+ * external configuration.
+ *
+ * Two modes:
+ *  1. **Schema-aware** — full schema known (from defineModelSchema / TOML).
+ *     Writes field metadata, constraints, and relationships.
+ *  2. **Infer-on-write** — no schema.  Infers types from record values.
+ */
+
+/**
+ * Infer a _meta_ type string from a JS runtime value.
+ */
+declare function inferFieldType(value: unknown): "string" | "number" | "boolean" | "stringset" | null;
+/**
+ * Register a named function default so metaSync can encode it.
+ * Called once per known default generator.
+ */
+declare function registerFunctionDefault(fn: Function, name: string): void;
+/**
+ * Clear the sync cache for a specific doc (or all docs).
+ * Useful for testing or when schema changes at runtime.
+ */
+declare function clearMetaSyncCache(yDoc?: Y.Doc): void;
+/**
+ * Sync full schema metadata into `_meta_{modelName}` inside a YDoc.
+ *
+ * Call this inside an existing `yDoc.transact()`.  Y.Map `.set()` on
+ * identical values is a CRDT no-op so there is no overhead after the
+ * first write.
+ *
+ * Skips the sync if this (yDoc, modelName) pair has already been synced
+ * in the current session.
+ */
+declare function syncModelMeta(yDoc: Y.Doc, modelName: string, schema: ModelSchemaRuntimeShape): void;
+/**
+ * Infer-on-write: when no schema is available, infer field types from
+ * the record data and write minimal _meta_.
+ *
+ * Call inside an existing `yDoc.transact()`.
+ */
+declare function syncInferredMeta(yDoc: Y.Doc, modelName: string, recordData: Record<string, any>): void;
+
+export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation, type AggregationOptions, type AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type ConnectDoDbOptions, type CountRequest, type CountResponse, DOClientEngine, type DOClientEngineConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DoDb, type DocumentFilter, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, type ErrorResponse, type GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, type InitJsBaoDOOptions, type InitJsBaoDOResult, type ModelAccessor, type PaginatedResult, type PatchOptions, type PatchRequest, type PatchResponse, type ProjectionSpec, type QueryOptions, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveOptions, type SaveRequest, type SaveResponse, type SortSpec, type StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, type WriteCondition, clearMetaSyncCache, connectDoDb, discoverModelNames, discoverSchema, getActiveDOEngine, inferFieldType, initJsBaoDO, loadSchemaFromTomlString, registerFunctionDefault, resetJsBaoDO, schemaToToml, syncInferredMeta, syncModelMeta };

package/dist/cloudflare.d.ts

@@ -938,9 +938,10 @@ declare class DOClientEngine extends DatabaseEngine {
     /**
      * Save a record to the DO.
      */
-    saveModel(modelName: string, id: string, data: Record<string, any>, stringSets?: Record<string, string[]>, options?: {
+    saveModel(modelName: string, id: string | undefined, data: Record<string, any>, stringSets?: Record<string, string[]>, options?: {
         ifNotExists?: boolean;
         condition?: DocumentFilter;
+        upsertOn?: string;
     }): Promise<string>;
     /**
      * Patch (partial update) a record in the DO.
@@ -1297,6 +1298,7 @@ interface SaveOptions {
     stringSets?: Record<string, string[]>;
     ifNotExists?: boolean;
     condition?: DocumentFilter;
+    upsertOn?: string;
 }
 interface PatchOptions {
     stringSets?: Record<string, string[]>;
@@ -1383,4 +1385,147 @@ interface DoDb {
  */
 declare function connectDoDb(options: ConnectDoDbOptions): DoDb;
 
-export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation, type AggregationOptions, type AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type ConnectDoDbOptions, type CountRequest, type CountResponse, DOClientEngine, type DOClientEngineConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DoDb, type DocumentFilter, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, type ErrorResponse, type GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, type InitJsBaoDOOptions, type InitJsBaoDOResult, type ModelAccessor, type PaginatedResult, type PatchOptions, type PatchRequest, type PatchResponse, type ProjectionSpec, type QueryOptions, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveOptions, type SaveRequest, type SaveResponse, type SortSpec, type StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, type WriteCondition, connectDoDb, getActiveDOEngine, initJsBaoDO, resetJsBaoDO };
+/**
+ * YDoc Schema Discovery
+ *
+ * Reads _meta_* YMaps from a YDoc and returns a plain JSON description
+ * of the schema.  Works with any YDoc — no BaseModel or database needed.
+ *
+ * Usage:
+ *   import { discoverSchema } from "js-bao";
+ *   const schema = discoverSchema(yDoc);
+ */
+
+interface DiscoveredField {
+    type: string;
+    indexed?: boolean;
+    unique?: boolean;
+    required?: boolean;
+    default?: string | number | boolean;
+    autoAssign?: boolean;
+    maxLength?: number;
+    maxCount?: number;
+}
+interface DiscoveredConstraint {
+    type: string;
+    fields: string[];
+}
+interface DiscoveredRelationship {
+    type: string;
+    model: string;
+    [key: string]: any;
+}
+interface DiscoveredModel {
+    fields: Record<string, DiscoveredField>;
+    constraints?: Record<string, DiscoveredConstraint>;
+    relationships?: Record<string, DiscoveredRelationship>;
+}
+interface DiscoveredSchema {
+    models: Record<string, DiscoveredModel>;
+}
+/**
+ * Discover the schema embedded in a YDoc by reading its `_meta_*` maps.
+ *
+ * Returns a plain JSON object describing every model that has metadata.
+ * Does not require BaseModel, a database, or any schema registration —
+ * just a Y.Doc.
+ */
+declare function discoverSchema(yDoc: Y.Doc): DiscoveredSchema;
+/**
+ * List model names that have data in the YDoc (non-`_` prefixed top-level maps).
+ */
+declare function discoverModelNames(yDoc: Y.Doc): string[];
+/**
+ * Convert a DiscoveredSchema to a TOML string matching the js-bao
+ * schema format.
+ *
+ * Usage:
+ *   const schema = discoverSchema(yDoc);
+ *   const toml = schemaToToml(schema);
+ */
+declare function schemaToToml(schema: DiscoveredSchema): string;
+
+interface ResolvedUniqueConstraint {
+    name: string;
+    fields: string[];
+}
+interface ModelSchemaRuntimeShape {
+    class: typeof BaseModel;
+    options: ModelOptions;
+    fields: Map<string, FieldOptions>;
+    resolvedUniqueConstraints: ResolvedUniqueConstraint[];
+}
+interface DefinedModelSchema<TFields extends Record<string, FieldOptions> = Record<string, FieldOptions>> {
+    name: string;
+    fields: TFields;
+    options: ModelOptions;
+    runtimeShape?: ModelSchemaRuntimeShape;
+    buildRuntimeShape(modelClass: typeof BaseModel): ModelSchemaRuntimeShape;
+}
+
+/**
+ * TOML Schema Loader
+ *
+ * Parses a TOML schema file and returns an array of DefinedModelSchema
+ * objects.  Can be used in place of manual `defineModelSchema()` calls.
+ *
+ * TOML conventions:
+ *  - Property names are snake_case (auto_assign, max_count, …)
+ *  - Model names and field names are as-is (user-chosen)
+ *  - Relationships live under [models.*.relationships.*]
+ *  - Compound unique constraints are [[models.*.unique_constraints]]
+ */
+
+/**
+ * Parse a TOML string and return an array of DefinedModelSchema objects.
+ */
+declare function loadSchemaFromTomlString(tomlString: string): DefinedModelSchema[];
+
+/**
+ * Meta Sync — writes _meta_* YMaps into a YDoc.
+ *
+ * Each model with data in a YDoc gets a `_meta_{modelName}` YMap that
+ * describes the model's fields, constraints, and relationships.  This
+ * lets any language that can read a YDoc discover the schema without
+ * external configuration.
+ *
+ * Two modes:
+ *  1. **Schema-aware** — full schema known (from defineModelSchema / TOML).
+ *     Writes field metadata, constraints, and relationships.
+ *  2. **Infer-on-write** — no schema.  Infers types from record values.
+ */
+
+/**
+ * Infer a _meta_ type string from a JS runtime value.
+ */
+declare function inferFieldType(value: unknown): "string" | "number" | "boolean" | "stringset" | null;
+/**
+ * Register a named function default so metaSync can encode it.
+ * Called once per known default generator.
+ */
+declare function registerFunctionDefault(fn: Function, name: string): void;
+/**
+ * Clear the sync cache for a specific doc (or all docs).
+ * Useful for testing or when schema changes at runtime.
+ */
+declare function clearMetaSyncCache(yDoc?: Y.Doc): void;
+/**
+ * Sync full schema metadata into `_meta_{modelName}` inside a YDoc.
+ *
+ * Call this inside an existing `yDoc.transact()`.  Y.Map `.set()` on
+ * identical values is a CRDT no-op so there is no overhead after the
+ * first write.
+ *
+ * Skips the sync if this (yDoc, modelName) pair has already been synced
+ * in the current session.
+ */
+declare function syncModelMeta(yDoc: Y.Doc, modelName: string, schema: ModelSchemaRuntimeShape): void;
+/**
+ * Infer-on-write: when no schema is available, infer field types from
+ * the record data and write minimal _meta_.
+ *
+ * Call inside an existing `yDoc.transact()`.
+ */
+declare function syncInferredMeta(yDoc: Y.Doc, modelName: string, recordData: Record<string, any>): void;
+
+export { type AfterQueryContext, type AfterQueryResult, type AggregateRequest, type AggregateResponse, type AggregationOperation, type AggregationOptions, type AggregationResult, type BatchOperation, type BatchOperationResult, type BatchRequest, type BatchResponse, type BeforeDeleteContext, type BeforeQueryContext, type BeforeQueryResult, type BeforeSaveContext, type ConnectDoDbOptions, type CountRequest, type CountResponse, DOClientEngine, type DOClientEngineConfig, type DatabaseDOHooks, type DeleteRequest, type DeleteResponse, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DoDb, type DocumentFilter, type DropIndexRequest, type DropIndexResponse, type DropUniqueConstraintRequest, type DropUniqueConstraintResponse, type ErrorResponse, type GroupByField, type HookContext, type HookResult, type IncrementRequest, type IncrementResponse, type IndexEntry, type IndexListResponse, type InitJsBaoDOOptions, type InitJsBaoDOResult, type ModelAccessor, type PaginatedResult, type PatchOptions, type PatchRequest, type PatchResponse, type ProjectionSpec, type QueryOptions, type QueryRequest, type QueryResponse, type RegisterIndexRequest, type RegisterIndexResponse, type RegisterUniqueConstraintRequest, type RegisterUniqueConstraintResponse, type SaveOptions, type SaveRequest, type SaveResponse, type SortSpec, type StringSetMembership, type StringSetUpdateRequest, type StringSetUpdateResponse, type SyncIndexesRequest, type SyncIndexesResponse, type UniqueConstraintEntry, type UniqueConstraintListResponse, type WriteCondition, clearMetaSyncCache, connectDoDb, discoverModelNames, discoverSchema, getActiveDOEngine, inferFieldType, initJsBaoDO, loadSchemaFromTomlString, registerFunctionDefault, resetJsBaoDO, schemaToToml, syncInferredMeta, syncModelMeta };