@typicalday/firegraph 0.3.0 → 0.5.0

package/dist/{index-CQkofEC_.d.cts → index-B9aodfYD.d.cts}

@@ -113,6 +113,8 @@ interface GraphRecord {
     data: Record<string, unknown>;
     createdAt: Timestamp | FieldValue;
     updatedAt: Timestamp | FieldValue;
+    /** Schema version — set automatically when the registry entry has migrations. */
+    v?: number;
 }
 interface StoredGraphRecord {
     aType: string;
@@ -123,6 +125,8 @@ interface StoredGraphRecord {
     data: Record<string, unknown>;
     createdAt: Timestamp;
     updatedAt: Timestamp;
+    /** Schema version — set automatically when the registry entry has migrations. */
+    v?: number;
 }
 interface WhereClause {
     field: string;
@@ -175,6 +179,45 @@ interface QueryFilter {
     op: WhereFilterOp;
     value: unknown;
 }
+/**
+ * An executable migration function that transforms data from one schema
+ * version to the next. Can be synchronous or asynchronous.
+ */
+type MigrationFn = (data: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+/**
+ * A single migration step in a registry entry.
+ * Transforms data from `fromVersion` to `toVersion`.
+ */
+interface MigrationStep {
+    fromVersion: number;
+    toVersion: number;
+    up: MigrationFn;
+}
+/**
+ * A stored migration step for dynamic registry types.
+ * The `up` field is a source code string that will be compiled at runtime.
+ *
+ * @example
+ * ```ts
+ * { fromVersion: 0, toVersion: 1, up: "(data) => ({ ...data, status: 'draft' })" }
+ * ```
+ */
+interface StoredMigrationStep {
+    fromVersion: number;
+    toVersion: number;
+    up: string;
+}
+/**
+ * Pluggable executor interface for compiling migration function source
+ * strings into executable functions. Used for dynamic registry migrations.
+ *
+ * The default executor uses SES (Secure ECMAScript) Compartments with
+ * JSON marshaling for isolation. Users can supply an alternative via
+ * `GraphClientOptions.migrationSandbox`.
+ */
+type MigrationExecutor = (source: string) => MigrationFn;
+/** Write-back mode for auto-migrated records. */
+type MigrationWriteBack = 'off' | 'eager' | 'background';
 interface RegistryEntry {
     aType: string;
     axbType: string;
@@ -220,6 +263,24 @@ interface RegistryEntry {
      * ```
      */
     targetGraph?: string;
+    /**
+     * Schema version for this type's data payload.
+     * **Computed automatically** from `migrations` as `max(toVersion)`.
+     * Do not set directly — provide migrations instead.
+     */
+    schemaVersion?: number;
+    /**
+     * Ordered list of migrations to transform data from older versions
+     * to the current version. The schema version is derived as the highest
+     * `toVersion` in this array.
+     */
+    migrations?: MigrationStep[];
+    /**
+     * Per-entry write-back override for auto-migrated records.
+     * Takes precedence over `GraphClientOptions.migrationWriteBack`.
+     * Omit to inherit the global setting.
+     */
+    migrationWriteBack?: MigrationWriteBack;
 }
 /** Topology declaration for an edge (from edge.json). */
 interface EdgeTopology {
@@ -255,6 +316,10 @@ interface DiscoveredEntity {
     allowedIn?: string[];
     /** Subgraph name where cross-graph edges of this type live. */
     targetGraph?: string;
+    /** Migration steps loaded from migrations.ts. */
+    migrations?: MigrationStep[];
+    /** Per-entity write-back override from meta.json. */
+    migrationWriteBack?: MigrationWriteBack;
 }
 /** Result of scanning an entities directory. */
 interface DiscoveryResult {
@@ -287,6 +352,18 @@ interface DefineTypeOptions {
     viewCss?: string;
     /** Scope patterns constraining where this type can exist in subgraphs. */
     allowedIn?: string[];
+    /**
+     * Migration steps. Accepts function objects (auto-serialized via .toString())
+     * or strings (stored as-is). The schema version is derived as the highest
+     * `toVersion` in this array.
+     */
+    migrations?: Array<{
+        fromVersion: number;
+        toVersion: number;
+        up: MigrationFn | string;
+    }>;
+    /** Per-type write-back override for auto-migrated records. */
+    migrationWriteBack?: MigrationWriteBack;
 }
 /** Data shape stored in a `nodeType` meta-node. */
 interface NodeTypeData {
@@ -298,6 +375,8 @@ interface NodeTypeData {
     viewTemplate?: string;
     viewCss?: string;
     allowedIn?: string[];
+    migrations?: StoredMigrationStep[];
+    migrationWriteBack?: MigrationWriteBack;
 }
 /** Data shape stored in an `edgeType` meta-node. */
 interface EdgeTypeData {
@@ -313,10 +392,21 @@ interface EdgeTypeData {
     viewCss?: string;
     allowedIn?: string[];
     targetGraph?: string;
+    migrations?: StoredMigrationStep[];
+    migrationWriteBack?: MigrationWriteBack;
 }
 type ScanProtection = 'error' | 'warn' | 'off';
 interface GraphClientOptions {
-    /** Static registry built from code/discovery. Ignored if registryMode is set. */
+    /**
+     * Static registry built from code/discovery.
+     *
+     * When provided alone, all writes are validated against this registry.
+     *
+     * When provided together with `registryMode`, operates in **merged mode**:
+     * static entries take priority and cannot be overridden by dynamic
+     * definitions. Dynamic definitions can only add new types. The merged
+     * client is returned as a `DynamicGraphClient`.
+     */
     registry?: GraphRegistry;
     /** Dynamic registry mode — type definitions stored as graph data. */
     registryMode?: DynamicRegistryConfig;
@@ -343,6 +433,25 @@ interface GraphClientOptions {
      * - `'off'` — No scan protection.
      */
     scanProtection?: ScanProtection;
+    /**
+     * Global default for write-back of auto-migrated records on read.
+     *
+     * - `'off'` (default) — Migrated data is returned but NOT written back.
+     * - `'eager'` — Migrated data is written back immediately after migration.
+     * - `'background'` — Write-back happens asynchronously; errors are logged.
+     *
+     * Per-entry `migrationWriteBack` on `RegistryEntry` overrides this setting.
+     */
+    migrationWriteBack?: MigrationWriteBack;
+    /**
+     * Custom executor for compiling dynamic registry migration source strings.
+     * Defaults to SES Compartments with JSON marshaling. Supply an
+     * alternative for custom sandboxing.
+     *
+     * Only used for dynamic registry migrations — static registry migrations
+     * are already in-memory functions and never go through this executor.
+     */
+    migrationSandbox?: MigrationExecutor;
 }
 interface GraphRegistry {
     validate(aType: string, axbType: string, bType: string, data: unknown, scopePath?: string): void;
@@ -531,4 +640,4 @@ interface CodegenOptions {
  */
 declare function generateTypes(discovery: DiscoveryResult, options?: CodegenOptions): Promise<string>;
 
-export { type ViewResolverConfig as A, type BulkBatchError as B, type CascadeResult as C, type DynamicRegistryConfig as D, type EdgeTopology as E, type FindEdgesParams as F, type GraphClientOptions as G, type HopDefinition as H, defineConfig as I, generateTypes as J, resolveView as K, type NodeTypeData as N, type QueryPlan as Q, type RegistryEntry as R, type ScanProtection as S, type TraversalBuilder as T, type ViewContext as V, type WhereClause as W, type DynamicGraphClient as a, type GraphClient as b, type DiscoveryResult as c, type GraphRegistry as d, type GraphReader as e, type GraphRecord as f, type FindNodesParams as g, type QueryFilter as h, type BulkOptions as i, type BulkProgress as j, type BulkResult as k, type CodegenOptions as l, type DefineTypeOptions as m, type DiscoveredEntity as n, type EdgeTypeData as o, type FiregraphConfig as p, type GraphBatch as q, type GraphTransaction as r, type GraphWriter as s, type HopResult as t, type QueryMode as u, type QueryOptions as v, type StoredGraphRecord as w, type TraversalOptions as x, type TraversalResult as y, type ViewDefaultsConfig as z };
+export { type ScanProtection as A, type BulkBatchError as B, type CascadeResult as C, type DynamicRegistryConfig as D, type EdgeTopology as E, type FindEdgesParams as F, type GraphClientOptions as G, type HopDefinition as H, type TraversalOptions as I, type TraversalResult as J, type ViewDefaultsConfig as K, type ViewResolverConfig as L, type MigrationExecutor as M, type NodeTypeData as N, defineConfig as O, generateTypes as P, type QueryPlan as Q, type RegistryEntry as R, type StoredMigrationStep as S, type TraversalBuilder as T, resolveView as U, type ViewContext as V, type WhereClause as W, type DynamicGraphClient as a, type GraphClient as b, type GraphRegistry as c, type DiscoveryResult as d, type GraphReader as e, type GraphRecord as f, type FindNodesParams as g, type MigrationFn as h, type MigrationStep as i, type StoredGraphRecord as j, type MigrationWriteBack as k, type QueryFilter as l, type BulkOptions as m, type BulkProgress as n, type BulkResult as o, type CodegenOptions as p, type DefineTypeOptions as q, type DiscoveredEntity as r, type EdgeTypeData as s, type FiregraphConfig as t, type GraphBatch as u, type GraphTransaction as v, type GraphWriter as w, type HopResult as x, type QueryMode as y, type QueryOptions as z };

package/dist/{index-CQkofEC_.d.ts → index-B9aodfYD.d.ts}

@@ -113,6 +113,8 @@ interface GraphRecord {
     data: Record<string, unknown>;
     createdAt: Timestamp | FieldValue;
     updatedAt: Timestamp | FieldValue;
+    /** Schema version — set automatically when the registry entry has migrations. */
+    v?: number;
 }
 interface StoredGraphRecord {
     aType: string;
@@ -123,6 +125,8 @@ interface StoredGraphRecord {
     data: Record<string, unknown>;
     createdAt: Timestamp;
     updatedAt: Timestamp;
+    /** Schema version — set automatically when the registry entry has migrations. */
+    v?: number;
 }
 interface WhereClause {
     field: string;
@@ -175,6 +179,45 @@ interface QueryFilter {
     op: WhereFilterOp;
     value: unknown;
 }
+/**
+ * An executable migration function that transforms data from one schema
+ * version to the next. Can be synchronous or asynchronous.
+ */
+type MigrationFn = (data: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+/**
+ * A single migration step in a registry entry.
+ * Transforms data from `fromVersion` to `toVersion`.
+ */
+interface MigrationStep {
+    fromVersion: number;
+    toVersion: number;
+    up: MigrationFn;
+}
+/**
+ * A stored migration step for dynamic registry types.
+ * The `up` field is a source code string that will be compiled at runtime.
+ *
+ * @example
+ * ```ts
+ * { fromVersion: 0, toVersion: 1, up: "(data) => ({ ...data, status: 'draft' })" }
+ * ```
+ */
+interface StoredMigrationStep {
+    fromVersion: number;
+    toVersion: number;
+    up: string;
+}
+/**
+ * Pluggable executor interface for compiling migration function source
+ * strings into executable functions. Used for dynamic registry migrations.
+ *
+ * The default executor uses SES (Secure ECMAScript) Compartments with
+ * JSON marshaling for isolation. Users can supply an alternative via
+ * `GraphClientOptions.migrationSandbox`.
+ */
+type MigrationExecutor = (source: string) => MigrationFn;
+/** Write-back mode for auto-migrated records. */
+type MigrationWriteBack = 'off' | 'eager' | 'background';
 interface RegistryEntry {
     aType: string;
     axbType: string;
@@ -220,6 +263,24 @@ interface RegistryEntry {
      * ```
      */
     targetGraph?: string;
+    /**
+     * Schema version for this type's data payload.
+     * **Computed automatically** from `migrations` as `max(toVersion)`.
+     * Do not set directly — provide migrations instead.
+     */
+    schemaVersion?: number;
+    /**
+     * Ordered list of migrations to transform data from older versions
+     * to the current version. The schema version is derived as the highest
+     * `toVersion` in this array.
+     */
+    migrations?: MigrationStep[];
+    /**
+     * Per-entry write-back override for auto-migrated records.
+     * Takes precedence over `GraphClientOptions.migrationWriteBack`.
+     * Omit to inherit the global setting.
+     */
+    migrationWriteBack?: MigrationWriteBack;
 }
 /** Topology declaration for an edge (from edge.json). */
 interface EdgeTopology {
@@ -255,6 +316,10 @@ interface DiscoveredEntity {
     allowedIn?: string[];
     /** Subgraph name where cross-graph edges of this type live. */
     targetGraph?: string;
+    /** Migration steps loaded from migrations.ts. */
+    migrations?: MigrationStep[];
+    /** Per-entity write-back override from meta.json. */
+    migrationWriteBack?: MigrationWriteBack;
 }
 /** Result of scanning an entities directory. */
 interface DiscoveryResult {
@@ -287,6 +352,18 @@ interface DefineTypeOptions {
     viewCss?: string;
     /** Scope patterns constraining where this type can exist in subgraphs. */
     allowedIn?: string[];
+    /**
+     * Migration steps. Accepts function objects (auto-serialized via .toString())
+     * or strings (stored as-is). The schema version is derived as the highest
+     * `toVersion` in this array.
+     */
+    migrations?: Array<{
+        fromVersion: number;
+        toVersion: number;
+        up: MigrationFn | string;
+    }>;
+    /** Per-type write-back override for auto-migrated records. */
+    migrationWriteBack?: MigrationWriteBack;
 }
 /** Data shape stored in a `nodeType` meta-node. */
 interface NodeTypeData {
@@ -298,6 +375,8 @@ interface NodeTypeData {
     viewTemplate?: string;
     viewCss?: string;
     allowedIn?: string[];
+    migrations?: StoredMigrationStep[];
+    migrationWriteBack?: MigrationWriteBack;
 }
 /** Data shape stored in an `edgeType` meta-node. */
 interface EdgeTypeData {
@@ -313,10 +392,21 @@ interface EdgeTypeData {
     viewCss?: string;
     allowedIn?: string[];
     targetGraph?: string;
+    migrations?: StoredMigrationStep[];
+    migrationWriteBack?: MigrationWriteBack;
 }
 type ScanProtection = 'error' | 'warn' | 'off';
 interface GraphClientOptions {
-    /** Static registry built from code/discovery. Ignored if registryMode is set. */
+    /**
+     * Static registry built from code/discovery.
+     *
+     * When provided alone, all writes are validated against this registry.
+     *
+     * When provided together with `registryMode`, operates in **merged mode**:
+     * static entries take priority and cannot be overridden by dynamic
+     * definitions. Dynamic definitions can only add new types. The merged
+     * client is returned as a `DynamicGraphClient`.
+     */
     registry?: GraphRegistry;
     /** Dynamic registry mode — type definitions stored as graph data. */
     registryMode?: DynamicRegistryConfig;
@@ -343,6 +433,25 @@ interface GraphClientOptions {
      * - `'off'` — No scan protection.
      */
     scanProtection?: ScanProtection;
+    /**
+     * Global default for write-back of auto-migrated records on read.
+     *
+     * - `'off'` (default) — Migrated data is returned but NOT written back.
+     * - `'eager'` — Migrated data is written back immediately after migration.
+     * - `'background'` — Write-back happens asynchronously; errors are logged.
+     *
+     * Per-entry `migrationWriteBack` on `RegistryEntry` overrides this setting.
+     */
+    migrationWriteBack?: MigrationWriteBack;
+    /**
+     * Custom executor for compiling dynamic registry migration source strings.
+     * Defaults to SES Compartments with JSON marshaling. Supply an
+     * alternative for custom sandboxing.
+     *
+     * Only used for dynamic registry migrations — static registry migrations
+     * are already in-memory functions and never go through this executor.
+     */
+    migrationSandbox?: MigrationExecutor;
 }
 interface GraphRegistry {
     validate(aType: string, axbType: string, bType: string, data: unknown, scopePath?: string): void;
@@ -531,4 +640,4 @@ interface CodegenOptions {
  */
 declare function generateTypes(discovery: DiscoveryResult, options?: CodegenOptions): Promise<string>;
 
-export { type ViewResolverConfig as A, type BulkBatchError as B, type CascadeResult as C, type DynamicRegistryConfig as D, type EdgeTopology as E, type FindEdgesParams as F, type GraphClientOptions as G, type HopDefinition as H, defineConfig as I, generateTypes as J, resolveView as K, type NodeTypeData as N, type QueryPlan as Q, type RegistryEntry as R, type ScanProtection as S, type TraversalBuilder as T, type ViewContext as V, type WhereClause as W, type DynamicGraphClient as a, type GraphClient as b, type DiscoveryResult as c, type GraphRegistry as d, type GraphReader as e, type GraphRecord as f, type FindNodesParams as g, type QueryFilter as h, type BulkOptions as i, type BulkProgress as j, type BulkResult as k, type CodegenOptions as l, type DefineTypeOptions as m, type DiscoveredEntity as n, type EdgeTypeData as o, type FiregraphConfig as p, type GraphBatch as q, type GraphTransaction as r, type GraphWriter as s, type HopResult as t, type QueryMode as u, type QueryOptions as v, type StoredGraphRecord as w, type TraversalOptions as x, type TraversalResult as y, type ViewDefaultsConfig as z };
+export { type ScanProtection as A, type BulkBatchError as B, type CascadeResult as C, type DynamicRegistryConfig as D, type EdgeTopology as E, type FindEdgesParams as F, type GraphClientOptions as G, type HopDefinition as H, type TraversalOptions as I, type TraversalResult as J, type ViewDefaultsConfig as K, type ViewResolverConfig as L, type MigrationExecutor as M, type NodeTypeData as N, defineConfig as O, generateTypes as P, type QueryPlan as Q, type RegistryEntry as R, type StoredMigrationStep as S, type TraversalBuilder as T, resolveView as U, type ViewContext as V, type WhereClause as W, type DynamicGraphClient as a, type GraphClient as b, type GraphRegistry as c, type DiscoveryResult as d, type GraphReader as e, type GraphRecord as f, type FindNodesParams as g, type MigrationFn as h, type MigrationStep as i, type StoredGraphRecord as j, type MigrationWriteBack as k, type QueryFilter as l, type BulkOptions as m, type BulkProgress as n, type BulkResult as o, type CodegenOptions as p, type DefineTypeOptions as q, type DiscoveredEntity as r, type EdgeTypeData as s, type FiregraphConfig as t, type GraphBatch as u, type GraphTransaction as v, type GraphWriter as w, type HopResult as x, type QueryMode as y, type QueryOptions as z };