js-bao 0.3.0 → 0.4.0

package/dist/browser.d.cts

@@ -663,9 +663,6 @@ declare class ModelRegistry {
     private validateSessionModels;
 }
 
-declare function Field(options: FieldOptions): (target: any, propertyKey: string | symbol) => void;
-declare function Model(options: ModelOptions): (targetClass: Function) => void;
-
 interface SQLJSEngineOptions {
     wasmURL?: string;
     locateFile?: (file: string) => string;
@@ -751,7 +748,7 @@ interface InitJsBaoOptions {
     /**
      * Optional array of model classes to initialize.
      * If not provided, the ORM will rely on models being registered
-     * via the @Model decorator (assuming they have been imported by the application).
+     * via attachAndRegisterModel (assuming they have been imported by the application).
      */
     models?: (typeof BaseModel)[];
 }
@@ -875,4 +872,129 @@ type HasManyThroughMethod<T> = (options?: PaginationOptions) => Promise<Paginate
 type AddRelationMethod<T> = (target: T | string) => Promise<void>;
 type RemoveRelationMethod<T> = (target: T | string) => Promise<void>;
 
-export { type AddRelationMethod, type AggregationAliasDebugInfo, type AggregationOperation, type AggregationOptions, type AggregationResult, BaseModel, type DatabaseConfig, DatabaseEngine, type DatabaseEngineType, BrowserDatabaseFactory as DatabaseFactory, 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 PaginatedResult, type PaginationOptions, RecordNotFoundError, type RefersToMethod, type RegisteredModelInfo, type RemoveRelationMethod, type SQLJSEngineOptions, type Schema, SqljsEngine, type SqljsEngineOptions, StringSet, type StringSetMembership, type UniqueConstraintConfig, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, createModelClass, defineModelSchema, detectEnvironment, features, generateULID, initJsBao, isBrowser, isNode, resetJsBao };
+/**
+ * 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[];
+
+/**
+ * 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 AddRelationMethod, type AggregationAliasDebugInfo, type AggregationOperation, type AggregationOptions, type AggregationResult, BaseModel, type DatabaseConfig, DatabaseEngine, type DatabaseEngineType, BrowserDatabaseFactory as DatabaseFactory, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type FieldOptions, type FieldType, type GroupByField, type HasManyMethod, type HasManyThroughMethod, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, type ModelConstructor, type ModelOptions, ModelRegistry, type PaginatedResult, type PaginationOptions, RecordNotFoundError, type RefersToMethod, type RegisteredModelInfo, type RemoveRelationMethod, type SQLJSEngineOptions, type Schema, SqljsEngine, type SqljsEngineOptions, StringSet, type StringSetMembership, type UniqueConstraintConfig, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, clearMetaSyncCache, createModelClass, defineModelSchema, detectEnvironment, discoverModelNames, discoverSchema, features, generateULID, inferFieldType, initJsBao, isBrowser, isNode, loadSchemaFromTomlString, registerFunctionDefault, resetJsBao, schemaToToml, syncInferredMeta, syncModelMeta };

package/dist/browser.d.ts

@@ -663,9 +663,6 @@ declare class ModelRegistry {
     private validateSessionModels;
 }
 
-declare function Field(options: FieldOptions): (target: any, propertyKey: string | symbol) => void;
-declare function Model(options: ModelOptions): (targetClass: Function) => void;
-
 interface SQLJSEngineOptions {
     wasmURL?: string;
     locateFile?: (file: string) => string;
@@ -751,7 +748,7 @@ interface InitJsBaoOptions {
     /**
      * Optional array of model classes to initialize.
      * If not provided, the ORM will rely on models being registered
-     * via the @Model decorator (assuming they have been imported by the application).
+     * via attachAndRegisterModel (assuming they have been imported by the application).
      */
     models?: (typeof BaseModel)[];
 }
@@ -875,4 +872,129 @@ type HasManyThroughMethod<T> = (options?: PaginationOptions) => Promise<Paginate
 type AddRelationMethod<T> = (target: T | string) => Promise<void>;
 type RemoveRelationMethod<T> = (target: T | string) => Promise<void>;
 
-export { type AddRelationMethod, type AggregationAliasDebugInfo, type AggregationOperation, type AggregationOptions, type AggregationResult, BaseModel, type DatabaseConfig, DatabaseEngine, type DatabaseEngineType, BrowserDatabaseFactory as DatabaseFactory, 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 PaginatedResult, type PaginationOptions, RecordNotFoundError, type RefersToMethod, type RegisteredModelInfo, type RemoveRelationMethod, type SQLJSEngineOptions, type Schema, SqljsEngine, type SqljsEngineOptions, StringSet, type StringSetMembership, type UniqueConstraintConfig, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, createModelClass, defineModelSchema, detectEnvironment, features, generateULID, initJsBao, isBrowser, isNode, resetJsBao };
+/**
+ * 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[];
+
+/**
+ * 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 AddRelationMethod, type AggregationAliasDebugInfo, type AggregationOperation, type AggregationOptions, type AggregationResult, BaseModel, type DatabaseConfig, DatabaseEngine, type DatabaseEngineType, BrowserDatabaseFactory as DatabaseFactory, type DiscoveredConstraint, type DiscoveredField, type DiscoveredModel, type DiscoveredRelationship, type DiscoveredSchema, type FieldOptions, type FieldType, type GroupByField, type HasManyMethod, type HasManyThroughMethod, type InferAttrs, type InitJsBaoOptions, type InitJsBaoResult, LogLevel, Logger, type ModelConstructor, type ModelOptions, ModelRegistry, type PaginatedResult, type PaginationOptions, RecordNotFoundError, type RefersToMethod, type RegisteredModelInfo, type RemoveRelationMethod, type SQLJSEngineOptions, type Schema, SqljsEngine, type SqljsEngineOptions, StringSet, type StringSetMembership, type UniqueConstraintConfig, UniqueConstraintViolationError, attachAndRegisterModel, attachSchemaToClass, autoRegisterModel, clearMetaSyncCache, createModelClass, defineModelSchema, detectEnvironment, discoverModelNames, discoverSchema, features, generateULID, inferFieldType, initJsBao, isBrowser, isNode, loadSchemaFromTomlString, registerFunctionDefault, resetJsBao, schemaToToml, syncInferredMeta, syncModelMeta };