@absolutejs/sync 0.8.0 → 0.10.0

package/dist/engine/schema.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Declarative, dependency-free row schemas keyed by table. The engine validates
+ * a mutation's writes against the schema before they're persisted (a bad write
+ * is rejected, like a permission deny), and lazily **migrates** rows on read —
+ * so changing a shape needs no up-front database migration. Field validators are
+ * plain `(value) => boolean` functions; the `field` kit covers the common cases.
+ */
+/** Validates one field's value. Optionality is encoded by the validator (see `field.optional`). */
+export type FieldValidator = (value: unknown) => boolean;
+export type TableSchema<Row = unknown> = {
+    /** Per-field validators. On insert every field is checked; on update, only
+     * the fields present in the payload. Extra fields not listed here are allowed. */
+    fields: Record<string, FieldValidator>;
+    /** Schema version, for documentation/migration bookkeeping. Default 1. */
+    version?: number;
+    /** Upcast a stored/raw row to the current shape — applied lazily on reads. */
+    migrate?: (row: Row) => Row;
+};
+/** A `table` → {@link TableSchema} map. */
+export type SchemaDefinition = Record<string, TableSchema<any>>;
+/**
+ * Define table schemas. Identity at runtime (for type inference). Pass to
+ * `createSyncEngine({ schemas })` or register with `engine.registerSchema`.
+ */
+export declare const defineSchema: <S extends SchemaDefinition>(schemas: S) => S;
+/** A small validator kit. Compose with `field.optional` / `field.array` / `field.enum`. */
+export declare const field: {
+    string: FieldValidator;
+    number: FieldValidator;
+    boolean: FieldValidator;
+    /** Any defined value. */
+    any: FieldValidator;
+    /** Allow `undefined` (the field may be omitted), else delegate to `inner`. */
+    optional: (inner: FieldValidator) => FieldValidator;
+    /** An array whose every element satisfies `inner`. */
+    array: (inner: FieldValidator) => FieldValidator;
+    /** One of the given literal values. */
+    enum: (...values: unknown[]) => FieldValidator;
+};

package/dist/engine/syncEngine.d.ts

@@ -6,6 +6,7 @@ import type { PermissionsDefinition, TablePermissions } from './permissions';
 import type { SearchCollectionDefinition } from './search';
 import type { ScheduleDefinition } from './schedule';
 import type { EngineActivity, EngineInspection } from './devtools';
+import type { SchemaDefinition, TableSchema } from './schema';
 import type { ClusterBus } from './cluster';
 import type { ChangeSource, RowChange, ViewDiff } from './types';
 /**
@@ -15,6 +16,13 @@ import type { ChangeSource, RowChange, ViewDiff } from './types';
 export declare class UnauthorizedError extends Error {
     constructor(subject: string);
 }
+/**
+ * Thrown when a mutation's write fails its table's schema (see
+ * {@link defineSchema}). The message names the offending field.
+ */
+export declare class SchemaError extends Error {
+    constructor(table: string, fieldName: string);
+}
 export type SubscribeArgs<T, P, Ctx> = {
     /** Registered collection name. */
     collection: string;
@@ -127,6 +135,20 @@ export type SyncEngine = {
      * `permissions` entry on {@link createSyncEngine}.
      */
     registerPermissions: <Row = unknown, Ctx = CollectionContext>(table: string, rules: TablePermissions<Row, Ctx>) => void;
+    /**
+     * Register a `table`'s schema (see {@link defineSchema}): writes are validated
+     * against it (a bad write rejects the mutation with {@link SchemaError}), and
+     * its `migrate` lazily upcasts rows on read. Equivalent to a `schemas` entry
+     * on {@link createSyncEngine}.
+     */
+    registerSchema: <Row = unknown>(table: string, schema: TableSchema<Row>) => void;
+    /**
+     * Apply a table's schema `migrate` to a raw/stored row (identity when there's
+     * no schema or migration). Use it wherever you read raw rows the engine
+     * doesn't (e.g. a search collection's `source`); the engine already migrates
+     * reactive `ctx.db` reads, view hydrates, and the one-shot hydrate.
+     */
+    migrate: <Row = unknown>(table: string, row: Row) => Row;
     /**
      * Run a registered mutation: authorize, invoke its handler (which writes and
      * emits changes via `applyChange`), and resolve with the handler's result.
@@ -169,6 +191,12 @@ export type SyncEngineOptions = {
      * (it threads `ctx` untyped to your rules).
      */
     permissions?: PermissionsDefinition<any>;
+    /**
+     * Declarative row schemas keyed by table (see {@link defineSchema}): writes
+     * are validated against them, and `migrate` lazily upcasts rows on read. Add
+     * more later with {@link SyncEngine.registerSchema}.
+     */
+    schemas?: SchemaDefinition;
 };
 /**
  * The Tier 3 sync engine: a registry of collections plus the view syncer. It is

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/sync",
-	"version": "0.8.0",
+	"version": "0.10.0",
 	"description": "Lightweight reactive-push and write-behind-cache primitives for Elysia and the AbsoluteJS ecosystem — kill polling and keep a remote store off your hot path, without adopting a whole sync-engine backend.",
 	"repository": {
 		"type": "git",
@@ -28,6 +28,11 @@
 			"import": "./dist/client/index.js",
 			"default": "./dist/client/index.js"
 		},
+		"./crdt": {
+			"types": "./dist/crdt/index.d.ts",
+			"import": "./dist/crdt/index.js",
+			"default": "./dist/crdt/index.js"
+		},
 		"./drizzle": {
 			"types": "./dist/adapters/drizzle/index.d.ts",
 			"import": "./dist/adapters/drizzle/index.js",