npm.io
0.77.0 • Published 1 week ago

@panproto/core

Licence
MIT
Version
0.77.0
Deps
1
Size
21.0 MB
Vulns
0
Weekly
0
Stars
84

@panproto/core

npm License: MIT

@panproto/core is the TypeScript wrapper around panproto-wasm. It supports Node.js 20 or newer and browser environments that can load the bundled wasm-bindgen assets.

The package is pre-1.0. A minor release may change the API, and the npm version follows the Rust workspace version.

Installation

npm install @panproto/core

The published package contains ESM and CommonJS entry points, TypeScript declarations, the wasm-bindgen JavaScript module, and the WebAssembly binary. It has no post-install script.

Quick start

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

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

using oldSchema = atproto.schema()
  .vertex('post', 'record', { nsid: 'app.test.post' })
  .vertex('post:body', 'object')
  .vertex('post:body.text', 'string')
  .edge('post', 'post:body', 'record-schema')
  .edge('post:body', 'post:body.text', 'prop', { name: 'text' })
  .build();

using newSchema = atproto.schema()
  .vertex('post', 'record', { nsid: 'app.test.post' })
  .vertex('post:body', 'object')
  .vertex('post:body.content', 'string')
  .edge('post', 'post:body', 'record-schema')
  .edge('post:body', 'post:body.content', 'prop', { name: 'content' })
  .build();

using lens = panproto.lens(oldSchema, newSchema);
const { view, complement } = lens.getJson(
  { text: 'hello' },
  'post:body',
);
const restoredSource = lens.putJson(view, complement, 'post:body');

getJson(record, rootVertex) projects a source JSON record to a target-shaped view. putJson(view, complement, rootVertex) reconstructs a source record. The lower-level get() and put() methods accept MessagePack bytes in the internal instance wire shape, not ordinary JavaScript records.

Migration direction

Compiled migration lift operations construct a target instance from the surviving mapped part of a source instance. The categorical transports are separate: Delta reindexes a target instance back to the source, while a general left Kan extension computes the source-to-target Sigma transport. The vocabulary in plain terms defines both.

Lens get projects source data to a target-shaped view and records discarded source data in a complement. Lens put uses the view and complement to reconstruct source data.

Symmetric-lens synchronization currently returns a LiftResult containing only the synchronized instance. The WASM boundary consumes the supplied complement but does not return the updated complement it computes internally. Thus callers must manage the complement passed to each synchronization call; syncLeftToRight and syncRightToLeft do not produce a replacement.

Conversion and query details

Panproto.convert(object, { from, to, rootVertex, defaults }) converts an ordinary JSON object. rootVertex is optional; when omitted, panproto selects an object-kind source vertex, falling back to a record-kind vertex. Specify it when the schema has more than one possible root. defaults supplies shallow fallback values for missing top-level fields. Values produced by the conversion take precedence. A Uint8Array is treated as an internal MessagePack WInstance, and cannot be combined with defaults.

executeQuery() keeps the public query and result fields in camel case. The wrapper translates them to Rust's MessagePack field names and passes the queried instance's schema handle to WASM. QueryMatch.nodeId is a number.

WASM loading and resource ownership

Panproto.init() dynamically imports the wasm-bindgen glue. In Node.js it reads the sibling .wasm file through node:fs. In a browser it lets the wasm-bindgen module fetch the sibling asset. Bundlers may instead pass a pre-imported glue module to Panproto.init().

Each call to Panproto.init() creates a new wrapper after loading and initializing the module. A Panproto instance caches built-in protocol handles by name. The loader does not keep a module-level initialization promise.

Schema, protocol, lens, migration, theory, repository, and data-set wrappers own WASM-side handles. These wrappers implement Symbol.dispose, and a FinalizationRegistry frees leaked handles as a fallback. Use using or call [Symbol.dispose]() explicitly for predictable release. Instance contains MessagePack bytes and does not own a handle.

The resource table is thread-local inside the WASM module. Do not transfer raw handle numbers between Workers. Create and use a complete Panproto object graph within each Worker.

API reference

API Current behavior
Panproto.protocol, Protocol, SchemaBuilder, BuiltSchema Read built-in protocol definitions and construct schemas. Panproto.listProtocols() returns the registry names from Rust.
Panproto.parseSchemaDocument, parseSchemaSource, parseSchemaBundle Parse supported schema documents, source languages, and ATProto bundles.
Panproto.diff, diffFull, FullDiffReport, CompatReport Compute structural changes and compatibility reports.
MigrationBuilder, CompiledMigration Define, compile, apply, compose, and invert source-to-target mappings.
Panproto.lens, LensHandle Generate and run complement-carrying asymmetric lenses.
Panproto.symmetricLens, SymmetricLensHandle Synchronize peer schemas in either direction. Each sync returns the destination instance; the caller manages the input complement because the current WASM boundary does not return an updated one.
Panproto.protolensChain, compileLensDocument, ProtolensChainHandle Generate, load, compose, and instantiate directional protolens chains. Accepted compiled documents retain their ordered value-level transforms; a symmetric body uses the separate symmetric-lens API.
Panproto.span Return a shared-schema span as plain data with quality_bounds and proven_optimal. No overlap produces an empty apex.
IoRegistry, Instance Parse and emit instance data. The default WASM registry contains 50 codecs.
TheoryHandle, TheoryBuilder, createTheory, colimit, checkMorphism Construct and check generalized algebraic theories and their morphisms.
Repository Operate on an in-memory VCS store. It does not open a Git repository on disk.
DataSetHandle Store data with a schema, migrate it, and check staleness.
ExprBuilder, parseExpr, evalExpr Construct, parse, format, and evaluate expressions.
executeQuery Query an Instance by anchor, predicate, grouping, projection, path, and limit.
fiberAt, fiberDecomposition, polyHom, preferredPath, distance Inspect migration fibers, internal homs, and conversion paths.

The declarations generated in dist/index.d.ts and the source types under src are the authoritative signatures.

Expression integers have Rust's signed 64-bit range. The Literal API uses a JavaScript number for values in the safe-integer range and a bigint for larger values. Pass large integer literals as bigint; passing an unsafe integer number is rejected rather than rounded.

Development

From this directory:

pnpm install
pnpm run build
pnpm run typecheck
pnpm test

The build runs wasm-pack, bundles the TypeScript entry points with tsup, and copies the generated WASM assets into dist.

Further reading

License

MIT

Keywords