@panproto/core

TypeScript SDK for panproto. Protocol-aware schema migration via generalized algebraic theories, with automatic lens generation via protolenses.

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.

Installation

npm install @panproto/core

Usage

import { Panproto } from '@panproto/core';

const panproto = await Panproto.init();
const atproto = panproto.protocol('atproto');

// 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();

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);

// 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);

// Build a reusable protolens chain (schema-independent)
const chain = panproto.protolensChain(oldSchema, newSchema);
const result = chain.apply(record);

// Factorize a theory morphism into elementary steps
const factors = panproto.factorizeMorphism(morphism);

API

Core

| 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 | | 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) |

Protolenses

| Export | Description | |--------|-------------| | 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

| 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

ATPROTO_SPEC, SQL_SPEC, PROTOBUF_SPEC, GRAPHQL_SPEC, JSON_SCHEMA_SPEC, BUILTIN_PROTOCOLS

Error classes

PanprotoError, WasmError, SchemaValidationError, MigrationError, ExistenceCheckError

Documentation

panproto.dev

License

MIT