@panproto/core 0.6.0 → 0.7.0

package/README.md

@@ -3,9 +3,9 @@
 [![npm](https://img.shields.io/npm/v/@panproto/core)](https://www.npmjs.com/package/@panproto/core)
 [![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
 
-TypeScript SDK for panproto. Protocol-aware schema migration via [generalized algebraic theories](https://ncatlab.org/nlab/show/generalized+algebraic+theory).
+TypeScript SDK for panproto. Protocol-aware schema migration via [generalized algebraic theories](https://ncatlab.org/nlab/show/generalized+algebraic+theory), with automatic lens generation via [protolenses](https://ncatlab.org/nlab/show/natural+transformation).
 
-This package wraps the panproto WASM module, providing a typed, ergonomic API for defining protocols, building schemas, computing migrations, and applying lens-based transformations from JavaScript and TypeScript.
+This package wraps the panproto WASM module, providing a typed, ergonomic API for defining protocols, building schemas, computing migrations, and applying protolens-based transformations from JavaScript and TypeScript.
 
 Requires Node.js >= 20.
 
@@ -23,26 +23,35 @@ import { Panproto } from '@panproto/core';
 const panproto = await Panproto.init();
 const atproto = panproto.protocol('atproto');
 
-// Build a schema
-const schema = atproto.schema()
+// Build schemas
+const oldSchema = atproto.schema()
   .vertex('post', 'record', { nsid: 'app.bsky.feed.post' })
   .vertex('post:body', 'object')
   .edge('post', 'post:body', 'record-schema')
   .build();
 
-// Diff two schemas
-const diff = panproto.diff(oldSchema, newSchema);
+const newSchema = atproto.schema()
+  .vertex('post', 'record', { nsid: 'app.bsky.feed.post' })
+  .vertex('post:body', 'object')
+  .vertex('post:body.title', 'string')
+  .edge('post', 'post:body', 'record-schema')
+  .edge('post:body', 'post:body.title', 'prop', { name: 'title' })
+  .build();
+
+// One-liner data conversion between schema versions
+const converted = panproto.convert(record, oldSchema, newSchema);
 
-// Compile and apply a migration
-const migration = panproto.migration(srcSchema, tgtSchema)
-  .map('old_id', 'new_id')
-  .compile();
+// Auto-generate a lens with full control
+const lens = panproto.lens(oldSchema, newSchema);
+const { view, complement } = lens.get(record);
+const restored = lens.put(modifiedView, complement);
 
-const lifted = migration.lift(record);
+// Build a reusable protolens chain (schema-independent)
+const chain = panproto.protolensChain(oldSchema, newSchema);
+const result = chain.apply(record);
 
-// Bidirectional lens
-const { view, complement } = migration.get(record);
-const restored = migration.put(modifiedView, complement);
+// Factorize a theory morphism into elementary steps
+const factors = panproto.factorizeMorphism(morphism);
 ```
 
 ## API
@@ -52,6 +61,10 @@ const restored = migration.put(modifiedView, complement);
 | Export | Description |
 |--------|-------------|
 | `Panproto` | Main entry point; call `Panproto.init()` to load the WASM module |
+| `Panproto.convert()` | One-liner data conversion between two schemas via auto-generated protolens |
+| `Panproto.lens()` | Auto-generate a lens between two schemas |
+| `Panproto.protolensChain()` | Build a reusable, schema-independent protolens chain |
+| `Panproto.factorizeMorphism()` | Decompose a theory morphism into elementary endofunctors |
 | `Protocol` | Protocol handle with schema builder factory |
 | `SchemaBuilder` / `BuiltSchema` | Fluent schema construction |
 | `MigrationBuilder` / `CompiledMigration` | Migration construction, compilation, and application |
@@ -59,13 +72,22 @@ const restored = migration.put(modifiedView, complement);
 | `IoRegistry` | Protocol-aware parse/emit for all 76 formats |
 | `Repository` | Schematic version control (init, commit, branch, merge) |
 
-### Lens combinators
+### Protolenses
 
 | Export | Description |
 |--------|-------------|
-| `renameField` / `addField` / `removeField` | Field-level transformations |
-| `wrapInObject` / `hoistField` / `coerceType` | Structural transformations |
-| `compose` / `pipeline` | Cambria-style combinator composition |
+| `LensHandle` | Lens with `get`, `put`, and `autoGenerate()` for automatic lens derivation |
+| `LensHandle.autoGenerate()` | Auto-generate a lens between two schemas |
+| `ProtolensChainHandle` | Reusable, schema-independent protolens chain with `apply` and `instantiate` |
+| `ProtolensChainHandle.fuse()` | Fuse chain into single step |
+| `ProtolensChainHandle.checkApplicability()` | Check applicability with reasons |
+| `ProtolensChainHandle.applyToFleet()` | Apply to multiple schemas |
+| `ProtolensChainHandle.lift()` | Lift along theory morphism |
+| `ProtolensChainHandle.fromJson()` | Deserialize from JSON |
+| `SymmetricLensHandle` | Symmetric (bidirectional) lens for two-way synchronization |
+| `DataSetHandle` | Handle to versioned data set with migrate/staleness methods |
+| `Panproto.dataSet()` | Store and track a data set |
+| `Panproto.migrateData()` | Migrate data between schemas |
 
 ### Breaking change analysis
 

package/dist/data.d.ts

@@ -0,0 +1,38 @@
+import { WasmModule } from './types.js';
+import { WasmHandle } from './wasm.js';
+import { BuiltSchema } from './schema.js';
+/** A handle to a versioned data set in the WASM store. */
+export declare class DataSetHandle implements Disposable {
+    #private;
+    constructor(handle: WasmHandle, wasm: WasmModule);
+    /** The WASM handle for this data set. Internal use only. */
+    get _handle(): WasmHandle;
+    /** Store a data set from a JavaScript object, bound to a schema. */
+    static fromData(data: unknown, schema: BuiltSchema, wasm: WasmModule): DataSetHandle;
+    /** Retrieve the data as MessagePack-encoded bytes. */
+    getData(): unknown;
+    /** Migrate this data set forward to a new schema. */
+    migrateForward(srcSchema: BuiltSchema, tgtSchema: BuiltSchema): MigrationResult;
+    /** Migrate this data set backward using a complement. */
+    migrateBackward(complement: Uint8Array, srcSchema: BuiltSchema, tgtSchema: BuiltSchema): DataSetHandle;
+    /** Check if this data set is stale relative to a schema. */
+    isStale(schema: BuiltSchema): StalenessResult;
+    [Symbol.dispose](): void;
+}
+/** Result of a forward data migration. */
+export interface MigrationResult {
+    /** The migrated data set at the target schema. */
+    readonly data: DataSetHandle;
+    /** The complement bytes needed for backward migration. */
+    readonly complement: Uint8Array;
+}
+/** Result of a staleness check. */
+export interface StalenessResult {
+    /** Whether the data set is stale relative to the target schema. */
+    readonly stale: boolean;
+    /** The schema ID the data was written against. */
+    readonly dataSchemaId: string;
+    /** The schema ID being compared to. */
+    readonly targetSchemaId: string;
+}
+//# sourceMappingURL=data.d.ts.map

package/dist/data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../src/data.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAgB,MAAM,WAAW,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,0DAA0D;AAC1D,qBAAa,aAAc,YAAW,UAAU;;gBAIlC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU;IAKhD,4DAA4D;IAC5D,IAAI,OAAO,IAAI,UAAU,CAExB;IAED,oEAAoE;IACpE,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,GAAG,aAAa;IAMpF,sDAAsD;IACtD,OAAO,IAAI,OAAO;IAKlB,qDAAqD;IACrD,cAAc,CAAC,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,GAAG,eAAe;IAmB/E,yDAAyD;IACzD,eAAe,CACb,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,WAAW,EACtB,SAAS,EAAE,WAAW,GACrB,aAAa;IAUhB,4DAA4D;IAC5D,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe;IAiB7C,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB;AAED,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uCAAuC;IACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC"}

package/dist/gat.d.ts

@@ -1,5 +1,6 @@
 import { WasmModule, TheorySpec, TheoryMorphism, MorphismCheckResult } from './types.js';
 import { WasmHandle } from './wasm.js';
+import { ElementaryStep } from './protolens.js';
 /**
  * A disposable handle to a WASM-side Theory resource.
  *
@@ -96,4 +97,19 @@ export declare function checkMorphism(morphism: TheoryMorphism, domain: TheoryHa
  * @returns Reindexed sort interpretations
  */
 export declare function migrateModel(sortInterp: Record<string, unknown[]>, morphism: TheoryMorphism, wasm: WasmModule): Record<string, unknown[]>;
+/**
+ * Factorize a morphism into elementary steps.
+ *
+ * Decomposes a theory morphism into a sequence of elementary schema
+ * transformations (renames, additions, removals, etc.) suitable for
+ * constructing protolens chains.
+ *
+ * @param morphismBytes - MessagePack-encoded morphism data
+ * @param domain - Handle to the domain theory
+ * @param codomain - Handle to the codomain theory
+ * @param wasm - The WASM module
+ * @returns A sequence of elementary steps
+ * @throws {@link WasmError} if factorization fails
+ */
+export declare function factorizeMorphism(morphismBytes: Uint8Array, domain: TheoryHandle, codomain: TheoryHandle, wasm: WasmModule): ElementaryStep[];
 //# sourceMappingURL=gat.d.ts.map

package/dist/gat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gat.d.ts","sourceRoot":"","sources":["../src/gat.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,mBAAmB,EAIpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAgB,MAAM,WAAW,CAAC;AAGrD;;;;GAIG;AACH,qBAAa,YAAa,YAAW,UAAU;;IAE7C,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;gBAEf,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU;IAKhD,0CAA0C;IAC1C,IAAI,OAAO,IAAI,UAAU,CAExB;IAED,6CAA6C;IAC7C,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;;gBAOZ,IAAI,EAAE,MAAM;IAQxB,wDAAwD;IACxD,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKjC,yCAAyC;IACzC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB,4CAA4C;IAC5C,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,IAAI;IAK3E,wBAAwB;IACxB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAKlE,+BAA+B;IAC/B,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,YAAY,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,YAAY,EAAE,IAAI,GAAG,IAAI;IAKtF,oCAAoC;IACpC,MAAM,IAAI,UAAU;IAUpB;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY;CAGtC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,YAAY,CAY7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,UAAU,GACf,YAAY,CAed;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,UAAU,GACf,mBAAmB,CAQrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EACrC,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,UAAU,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAK3B"}
+{"version":3,"file":"gat.d.ts","sourceRoot":"","sources":["../src/gat.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,mBAAmB,EAIpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAgB,MAAM,WAAW,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;GAIG;AACH,qBAAa,YAAa,YAAW,UAAU;;IAE7C,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;gBAEf,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU;IAKhD,0CAA0C;IAC1C,IAAI,OAAO,IAAI,UAAU,CAExB;IAED,6CAA6C;IAC7C,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;;gBAOZ,IAAI,EAAE,MAAM;IAQxB,wDAAwD;IACxD,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKjC,yCAAyC;IACzC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB,4CAA4C;IAC5C,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,IAAI;IAK3E,wBAAwB;IACxB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAKlE,+BAA+B;IAC/B,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,YAAY,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,YAAY,EAAE,IAAI,GAAG,IAAI;IAKtF,oCAAoC;IACpC,MAAM,IAAI,UAAU;IAUpB;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY;CAGtC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,YAAY,CAY7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,YAAY,EAChB,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,UAAU,GACf,YAAY,CAed;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,UAAU,GACf,mBAAmB,CAQrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,EACrC,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,UAAU,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAK3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,UAAU,EACzB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,UAAU,GACf,cAAc,EAAE,CAUlB"}