js-bao 0.3.0 → 0.3.1

package/dist/node.d.cts

@@ -904,6 +904,136 @@ type HasManyThroughMethod<T> = (options?: PaginationOptions) => Promise<Paginate
 type AddRelationMethod<T> = (target: T | string) => Promise<void>;
 type RemoveRelationMethod<T> = (target: T | string) => Promise<void>;
 
+/**
+ * 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;
+
+/**
+ * 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[];
+/**
+ * Read a TOML file from disk and return an array of DefinedModelSchema objects.
+ * Only available in Node.js environments.
+ */
+declare function loadSchemaFromToml(filePath: string): Promise<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;
+
 interface DumpOptions {
     includeIndexes?: boolean;
 }
@@ -947,4 +1077,4 @@ declare function summarizePlainYDoc(dump: PlainYDoc): DumpSummary;
 
 declare function getRecommendedNodeEngine(): Promise<string>;
 
-export { type AddRelationMethod, type AggregationAliasDebugInfo, type AggregationOperation, type AggregationOptions, type AggregationResult, BaseModel, type DatabaseConfig, DatabaseEngine, type DatabaseEngineOptions, type DatabaseEngineType, NodeDatabaseFactory as DatabaseFactory, type DumpOptions, type DumpSummary, type DumpSummaryEntry, Field, type FieldOptions, type FieldType, type GroupByField, type HasManyMethod, type HasManyThroughMethod, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, Model, type ModelConstructor, type ModelOptions, ModelRegistry, type NodeSqliteEngineOptions, type PaginatedResult, type PaginationOptions, type PlainYDoc, RecordNotFoundError, type RefersToMethod, type RegisteredModelInfo, type RemoveRelationMethod, type SQLJSEngineOptions, type Schema, SqljsEngine, type SqljsEngineOptions, StringSet, type StringSetMembership, type UniqueConstraintConfig, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, constants, createModelClass, defineModelSchema, detectEnvironment, dumpYDocToPlain, features, generateULID, getRecommendedNodeEngine, initJsBao, isBrowser, isNode, isNodeModuleAvailable, resetJsBao, summarizePlainYDoc };
+export { type AddRelationMethod, type AggregationAliasDebugInfo, type AggregationOperation, type AggregationOptions, type AggregationResult, BaseModel, type DatabaseConfig, DatabaseEngine, type DatabaseEngineOptions, type DatabaseEngineType, NodeDatabaseFactory as DatabaseFactory, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DumpOptions, type DumpSummary, type DumpSummaryEntry, Field, type FieldOptions, type FieldType, type GroupByField, type HasManyMethod, type HasManyThroughMethod, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, Model, type ModelConstructor, type ModelOptions, ModelRegistry, type NodeSqliteEngineOptions, type PaginatedResult, type PaginationOptions, type PlainYDoc, RecordNotFoundError, type RefersToMethod, type RegisteredModelInfo, type RemoveRelationMethod, type SQLJSEngineOptions, type Schema, SqljsEngine, type SqljsEngineOptions, StringSet, type StringSetMembership, type UniqueConstraintConfig, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, clearMetaSyncCache, constants, createModelClass, defineModelSchema, detectEnvironment, discoverModelNames, discoverSchema, dumpYDocToPlain, features, generateULID, getRecommendedNodeEngine, inferFieldType, initJsBao, isBrowser, isNode, isNodeModuleAvailable, loadSchemaFromToml, loadSchemaFromTomlString, registerFunctionDefault, resetJsBao, schemaToToml, summarizePlainYDoc, syncInferredMeta, syncModelMeta };

package/dist/node.d.ts

@@ -904,6 +904,136 @@ type HasManyThroughMethod<T> = (options?: PaginationOptions) => Promise<Paginate
 type AddRelationMethod<T> = (target: T | string) => Promise<void>;
 type RemoveRelationMethod<T> = (target: T | string) => Promise<void>;
 
+/**
+ * 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;
+
+/**
+ * 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[];
+/**
+ * Read a TOML file from disk and return an array of DefinedModelSchema objects.
+ * Only available in Node.js environments.
+ */
+declare function loadSchemaFromToml(filePath: string): Promise<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;
+
 interface DumpOptions {
     includeIndexes?: boolean;
 }
@@ -947,4 +1077,4 @@ declare function summarizePlainYDoc(dump: PlainYDoc): DumpSummary;
 
 declare function getRecommendedNodeEngine(): Promise<string>;
 
-export { type AddRelationMethod, type AggregationAliasDebugInfo, type AggregationOperation, type AggregationOptions, type AggregationResult, BaseModel, type DatabaseConfig, DatabaseEngine, type DatabaseEngineOptions, type DatabaseEngineType, NodeDatabaseFactory as DatabaseFactory, type DumpOptions, type DumpSummary, type DumpSummaryEntry, Field, type FieldOptions, type FieldType, type GroupByField, type HasManyMethod, type HasManyThroughMethod, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, Model, type ModelConstructor, type ModelOptions, ModelRegistry, type NodeSqliteEngineOptions, type PaginatedResult, type PaginationOptions, type PlainYDoc, RecordNotFoundError, type RefersToMethod, type RegisteredModelInfo, type RemoveRelationMethod, type SQLJSEngineOptions, type Schema, SqljsEngine, type SqljsEngineOptions, StringSet, type StringSetMembership, type UniqueConstraintConfig, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, constants, createModelClass, defineModelSchema, detectEnvironment, dumpYDocToPlain, features, generateULID, getRecommendedNodeEngine, initJsBao, isBrowser, isNode, isNodeModuleAvailable, resetJsBao, summarizePlainYDoc };
+export { type AddRelationMethod, type AggregationAliasDebugInfo, type AggregationOperation, type AggregationOptions, type AggregationResult, BaseModel, type DatabaseConfig, DatabaseEngine, type DatabaseEngineOptions, type DatabaseEngineType, NodeDatabaseFactory as DatabaseFactory, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type DumpOptions, type DumpSummary, type DumpSummaryEntry, Field, type FieldOptions, type FieldType, type GroupByField, type HasManyMethod, type HasManyThroughMethod, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, Model, type ModelConstructor, type ModelOptions, ModelRegistry, type NodeSqliteEngineOptions, type PaginatedResult, type PaginationOptions, type PlainYDoc, RecordNotFoundError, type RefersToMethod, type RegisteredModelInfo, type RemoveRelationMethod, type SQLJSEngineOptions, type Schema, SqljsEngine, type SqljsEngineOptions, StringSet, type StringSetMembership, type UniqueConstraintConfig, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, clearMetaSyncCache, constants, createModelClass, defineModelSchema, detectEnvironment, discoverModelNames, discoverSchema, dumpYDocToPlain, features, generateULID, getRecommendedNodeEngine, inferFieldType, initJsBao, isBrowser, isNode, isNodeModuleAvailable, loadSchemaFromToml, loadSchemaFromTomlString, registerFunctionDefault, resetJsBao, schemaToToml, summarizePlainYDoc, syncInferredMeta, syncModelMeta };