@panproto/core 0.5.0 → 0.5.1

package/README.md

@@ -1,8 +1,13 @@
 # @panproto/core
 
-TypeScript SDK for panproto -- protocol-aware schema migration via [generalized algebraic theories](https://ncatlab.org/nlab/show/generalized+algebraic+theory).
+[![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)
 
-This package wraps the panproto [WASM](https://webassembly.org/) module, providing a typed, ergonomic API for defining protocols, building schemas, computing migrations, and applying [lens](https://ncatlab.org/nlab/show/lens+%28in+computer+science%29)-based transformations from JavaScript and TypeScript.
+TypeScript SDK for panproto. Protocol-aware schema migration via [generalized algebraic theories](https://ncatlab.org/nlab/show/generalized+algebraic+theory).
+
+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.
+
+Requires Node.js >= 20.
 
 ## Installation
 
@@ -10,8 +15,6 @@ This package wraps the panproto [WASM](https://webassembly.org/) module, providi
 npm install @panproto/core
 ```
 
-Requires Node.js >= 20.
-
 ## Usage
 
 ```typescript
@@ -32,10 +35,14 @@ const diff = panproto.diff(oldSchema, newSchema);
 
 // Compile and apply a migration
 const migration = panproto.migration(srcSchema, tgtSchema)
-  .mapVertex('old_id', 'new_id')
+  .map('old_id', 'new_id')
   .compile();
 
 const lifted = migration.lift(record);
+
+// Bidirectional lens
+const { view, complement } = migration.get(record);
+const restored = migration.put(modifiedView, complement);
 ```
 
 ## API
@@ -47,24 +54,47 @@ const lifted = migration.lift(record);
 | `Panproto` | Main entry point; call `Panproto.init()` to load the WASM module |
 | `Protocol` | Protocol handle with schema builder factory |
 | `SchemaBuilder` / `BuiltSchema` | Fluent schema construction |
-| `MigrationBuilder` / `CompiledMigration` | Migration construction and compilation |
+| `MigrationBuilder` / `CompiledMigration` | Migration construction, compilation, and application |
+| `Instance` | Instance wrapper with JSON conversion and validation |
+| `IoRegistry` | Protocol-aware parse/emit for all 76 formats |
+| `Repository` | Schematic version control (init, commit, branch, merge) |
 
-### Lens Combinators
+### Lens combinators
 
 | Export | Description |
 |--------|-------------|
 | `renameField` / `addField` / `removeField` | Field-level transformations |
 | `wrapInObject` / `hoistField` / `coerceType` | Structural transformations |
-| `compose` / `pipeline` | [Cambria](https://www.inkandswitch.com/cambria/)-style combinator composition |
+| `compose` / `pipeline` | Cambria-style combinator composition |
+
+### Breaking change analysis
+
+| Export | Description |
+|--------|-------------|
+| `FullDiffReport` | Comprehensive structural diff between two schemas |
+| `CompatReport` | Protocol-aware classification into breaking/non-breaking |
+| `ValidationResult` | Schema validation against protocol rules |
+
+### GAT engine
+
+| Export | Description |
+|--------|-------------|
+| `TheoryHandle` / `TheoryBuilder` | Theory construction |
+| `createTheory` / `colimit` | Build and compose theories |
+| `checkMorphism` / `migrateModel` | Morphism validation and model transport |
 
-### Built-in Protocol Specs
+### Built-in protocol specs
 
 `ATPROTO_SPEC`, `SQL_SPEC`, `PROTOBUF_SPEC`, `GRAPHQL_SPEC`, `JSON_SCHEMA_SPEC`, `BUILTIN_PROTOCOLS`
 
-### Error Classes
+### Error classes
 
 `PanprotoError`, `WasmError`, `SchemaValidationError`, `MigrationError`, `ExistenceCheckError`
 
+## Documentation
+
+[panproto.dev](https://panproto.dev)
+
 ## License
 
 [MIT](../../LICENSE)

package/dist/index.cjs

@@ -66,6 +66,10 @@ async function loadWasm(input) {
       validate_instance: glue.validate_instance,
       instance_to_json: glue.instance_to_json,
       json_to_instance: glue.json_to_instance,
+      json_to_instance_with_root: glue.json_to_instance_with_root,
+      lift_json: glue.lift_json,
+      get_json: glue.get_json,
+      put_json: glue.put_json,
       instance_element_count: glue.instance_element_count,
       lens_from_combinators: glue.lens_from_combinators,
       check_lens_laws: glue.check_lens_laws,
@@ -158,7 +162,14 @@ function packSchemaOps(ops) {
   return msgpack.encode(ops);
 }
 function packMigrationMapping(mapping) {
-  return msgpack.encode(mapping);
+  return msgpack.encode({
+    vertex_map: mapping.vertex_map,
+    edge_map: Array.from(mapping.edge_map.entries()),
+    hyper_edge_map: mapping.hyper_edge_map,
+    label_map: Array.from(mapping.label_map.entries()),
+    resolver: Array.from(mapping.resolver.entries()),
+    hyper_resolver: []
+  });
 }
 function renameField(oldName, newName) {
   return { type: "rename-field", old: oldName, new: newName };
@@ -1119,6 +1130,10 @@ class CompiledMigration {
   get _handle() {
     return this.#handle;
   }
+  /** The WASM module. Internal use only. */
+  get _wasm() {
+    return this.#wasm;
+  }
   /** The migration specification used to build this migration. */
   get spec() {
     return this.#spec;
@@ -1126,22 +1141,22 @@ class CompiledMigration {
   /**
    * Transform a record using this migration (forward direction).
    *
-   * This is the hot path: data goes through WASM as MessagePack bytes
-   * with no intermediate JS-heap allocation.
+   * Accepts either a raw JS object (which will be msgpack-encoded) or
+   * an `Instance` (whose pre-encoded bytes are passed directly to WASM).
    *
-   * @param record - The input record to transform
+   * @param record - The input record or Instance to transform
    * @returns The transformed record
    * @throws {@link WasmError} if the WASM call fails
    */
   lift(record) {
-    const inputBytes = packToWasm(record);
+    const inputBytes = record && typeof record === "object" && "_bytes" in record ? record._bytes : packToWasm(record);
     try {
       const outputBytes = this.#wasm.exports.lift_record(
         this.#handle.id,
         inputBytes
       );
       const data = unpackFromWasm(outputBytes);
-      return { data };
+      return { data, _rawBytes: outputBytes };
     } catch (error) {
       throw new WasmError(
         `lift_record failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -1160,7 +1175,7 @@ class CompiledMigration {
    * @throws {@link WasmError} if the WASM call fails
    */
   get(record) {
-    const inputBytes = packToWasm(record);
+    const inputBytes = record && typeof record === "object" && "_bytes" in record ? record._bytes : packToWasm(record);
     try {
       const outputBytes = this.#wasm.exports.get_record(
         this.#handle.id,
@@ -1187,7 +1202,7 @@ class CompiledMigration {
    * @throws {@link WasmError} if the WASM call fails
    */
   put(view, complement) {
-    const viewBytes = packToWasm(view);
+    const viewBytes = view && typeof view === "object" && "_bytes" in view ? view._bytes : packToWasm(view);
     try {
       const outputBytes = this.#wasm.exports.put_record(
         this.#handle.id,