@1kbgz/transports 0.3.0 → 0.6.0

package/dist/esm/src/ts/client.d.ts

@@ -0,0 +1,99 @@
+import type { Value } from "./bridge";
+export type PathSeg = {
+    Key: string;
+} | {
+    Index: number;
+};
+export type PatchOp = {
+    Set: {
+        path: PathSeg[];
+        value: Value;
+    };
+} | {
+    Remove: {
+        path: PathSeg[];
+    };
+} | {
+    Insert: {
+        path: PathSeg[];
+        index: number;
+        value: Value;
+    };
+} | {
+    RemoveAt: {
+        path: PathSeg[];
+        index: number;
+    };
+};
+export type ModelPatch = {
+    rev: number;
+    ops: PatchOp[];
+};
+type PatchMsg = {
+    t: "patch";
+    id: number;
+    patch: ModelPatch;
+};
+/** Frame metadata returned after the mirror accepts a snapshot or patch. */
+export type ReceiveChange = {
+    t: "snapshot";
+    id: number;
+    rev: number;
+} | PatchMsg;
+/** Mirrors a remote transports `Session` from connection messages.
+ *
+ * Inbound frames are decoded by type — text frames are JSON, binary frames are MessagePack — so a
+ * client transparently mirrors a server regardless of the negotiated codec. Binary built-in codecs
+ * and edit generation require the wasm core to be initialized.
+ */
+export declare class Client {
+    private codec;
+    private values;
+    private revs;
+    constructor(codec?: string);
+    /** Apply an inbound snapshot or patch frame to the mirror.
+     *
+     * Decodes by the client's codec: a registered custom codec, else built-in JSON (text) / msgpack
+     * (binary). Returns the accepted change so reactive adapters can update only its paths; returns
+     * `undefined` for a patch whose revision was already applied. The returned change and values from
+     * `value()` share immutable branches with the mirror; consumers must not mutate them. Invalid frames
+     * throw without changing the mirror or its accepted revision.
+     */
+    recv(data: string | Uint8Array): ReceiveChange | undefined;
+    /** The current mirrored core `Value` of a model. */
+    value(id: number): unknown;
+    ids(): number[];
+    /** Propose an edit to a mirrored model; returns the patch frame to send (encoded in this codec).
+     *
+     * Server-authoritative: the local mirror updates when the server echoes the authoritative patch
+     * back via `recv`, not optimistically.
+     */
+    edit(id: number, value: unknown): string | Uint8Array;
+    /** Connect to a transports server and mirror it. Returns the `WebSocket`.
+     *
+     * On a reconnect (this client already mirrors models) it appends `?since=` with its last-seen rev per
+     * model, so the server replays only the delta instead of re-sending each whole model.
+     */
+    connect(url: string): WebSocket;
+    /** Connect and mirror, **reconnecting** whenever the socket drops — so the client survives a server
+     * restart or a refresh. `authority` decides reconciliation on each (re)connect:
+     *
+     * - `"server"` (default): the server is canonical; the client adopts its state (resuming via `?since=`
+     *   when it can, else a fresh snapshot) — the "refetch on refresh" behavior.
+     * - `"client"`: the client is canonical; after the server's snapshot it pushes its last-known state
+     *   back as an edit, rectifying a server that came back stale/empty (merges under a CRDT, else
+     *   overwrites).
+     *
+     * `onMessage` fires after each applied frame (e.g. to re-render). Returns `{ stop() }`.
+     */
+    run(url: string, opts?: {
+        authority?: "server" | "client";
+        retry?: number;
+        onMessage?: () => void;
+    }): {
+        stop: () => void;
+    };
+    /** Mirror a server over Server-Sent Events (receive-only, JSON). Returns the `EventSource`. */
+    connectSSE(url: string): EventSource;
+}
+export {};

package/dist/esm/src/ts/codecs.d.ts

@@ -0,0 +1,17 @@
+/** Custom wire codec registry (the JS analog of `transports.register_codec` in Python).
+ *
+ * A codec turns a JSON-able object (a protocol message, or a model `Value`) into a wire frame
+ * (`string` or `Uint8Array`) and back. Register a matching implementation here for any content type
+ * you also register on the server, then use it via `new Client(contentType)` / `?codec=`.
+ */
+export type CodecEncode = (obj: unknown) => string | Uint8Array;
+export type CodecDecode = (data: string | Uint8Array) => unknown;
+/** Register a custom codec under `contentType`. The built-in json/msgpack codecs cannot be overridden. */
+export declare function registerCodec(contentType: string, encode: CodecEncode, decode: CodecDecode): void;
+/** Remove a previously registered custom codec. */
+export declare function unregisterCodec(contentType: string): void;
+/** The currently registered custom codec for `contentType`, if any. */
+export declare function codecFor(contentType: string): {
+    encode: CodecEncode;
+    decode: CodecDecode;
+} | undefined;

package/dist/esm/src/ts/index.d.ts

@@ -0,0 +1,31 @@
+import * as wasm from "../../dist/pkg/transports";
+export * as wasm from "../../dist/pkg/transports";
+export declare const placeholder = "";
+/** Diff two JSON-encoded models, returning the JSON-encoded patch. */
+export declare const diff: (oldModel: string, newModel: string) => string;
+/** Apply a JSON-encoded patch to a JSON-encoded model, returning the JSON-encoded result. */
+export declare const apply: (model: string, patch: string) => string;
+/** Encode a JSON-encoded model to codec bytes. */
+export declare const encode: (model: string) => Uint8Array;
+/** Decode codec bytes back to a JSON-encoded model string. */
+export declare const decode: (bytes: Uint8Array) => string;
+/** Encode a JSON-encoded model with the codec named by `codec` (e.g. "application/msgpack"). */
+export declare const encodeAs: (model: string, codec: string) => Uint8Array;
+/** Decode bytes (from `codec`'s codec) back to a JSON-encoded model string. */
+export declare const decodeAs: (bytes: Uint8Array, codec: string) => string;
+/** Convert an arbitrary JSON document to MessagePack bytes (for whole protocol messages). */
+export declare const jsonToMsgpack: (json: string) => Uint8Array;
+/** Convert MessagePack bytes back to a JSON document. */
+export declare const msgpackToJson: (bytes: Uint8Array) => string;
+/** Convert an arbitrary JSON document to CBOR bytes (for whole protocol messages). */
+export declare const jsonToCbor: (json: string) => Uint8Array;
+/** Convert CBOR bytes back to a JSON document. */
+export declare const cborToJson: (bytes: Uint8Array) => string;
+/** In-process model store: host / mutate → patch / apply / snapshot. */
+export declare const Store: typeof wasm.Store;
+export { toValue, fromValue } from "./bridge";
+export type { Value } from "./bridge";
+export { Client } from "./client";
+export type { ModelPatch, PatchOp, PathSeg, ReceiveChange } from "./client";
+export { registerCodec, unregisterCodec, codecFor } from "./codecs";
+export type { CodecEncode, CodecDecode } from "./codecs";

package/dist/pkg/transports.d.ts

@@ -31,6 +31,11 @@ export class Store {
  */
 export function apply(value: string, patch: string): string;
 
+/**
+ * Convert CBOR bytes back to a JSON document.
+ */
+export function cbor_to_json(data: Uint8Array): string;
+
 /**
  * Decode codec bytes back to a JSON-encoded model string.
  */
@@ -56,6 +61,11 @@ export function encode(value: string): Uint8Array;
  */
 export function encode_as(value: string, codec: string): Uint8Array;
 
+/**
+ * Convert an arbitrary JSON document to CBOR bytes (a `Uint8Array` in JS).
+ */
+export function json_to_cbor(json: string): Uint8Array;
+
 /**
  * Convert an arbitrary JSON document to MessagePack bytes (a `Uint8Array` in JS).
  */
@@ -70,20 +80,22 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
-    readonly diff: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly __wbg_store_free: (a: number, b: number) => void;
     readonly apply: (a: number, b: number, c: number, d: number) => [number, number, number, number];
-    readonly encode: (a: number, b: number) => [number, number, number, number];
+    readonly cbor_to_json: (a: number, b: number) => [number, number, number, number];
     readonly decode: (a: number, b: number) => [number, number, number, number];
-    readonly encode_as: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly decode_as: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly diff: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly encode: (a: number, b: number) => [number, number, number, number];
+    readonly encode_as: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly json_to_cbor: (a: number, b: number) => [number, number, number, number];
     readonly json_to_msgpack: (a: number, b: number) => [number, number, number, number];
     readonly msgpack_to_json: (a: number, b: number) => [number, number, number, number];
-    readonly __wbg_store_free: (a: number, b: number) => void;
-    readonly store_new: () => number;
+    readonly store_apply: (a: number, b: bigint, c: number, d: number) => [number, number, number];
     readonly store_host: (a: number, b: number, c: number, d: number, e: number) => [bigint, number, number];
-    readonly store_snapshot: (a: number, b: bigint) => [number, number];
     readonly store_mutate: (a: number, b: bigint, c: number, d: number) => [number, number, number, number];
-    readonly store_apply: (a: number, b: bigint, c: number, d: number) => [number, number, number];
+    readonly store_new: () => number;
+    readonly store_snapshot: (a: number, b: bigint) => [number, number];
     readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;

package/dist/pkg/transports.js

@@ -118,6 +118,32 @@ export function apply(value, patch) {
     }
 }
 
+/**
+ * Convert CBOR bytes back to a JSON document.
+ * @param {Uint8Array} data
+ * @returns {string}
+ */
+export function cbor_to_json(data) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.cbor_to_json(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
 /**
  * Decode codec bytes back to a JSON-encoded model string.
  * @param {Uint8Array} data
@@ -239,6 +265,23 @@ export function encode_as(value, codec) {
     return v3;
 }
 
+/**
+ * Convert an arbitrary JSON document to CBOR bytes (a `Uint8Array` in JS).
+ * @param {string} json
+ * @returns {Uint8Array}
+ */
+export function json_to_cbor(json) {
+    const ptr0 = passStringToWasm0(json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.json_to_cbor(ptr0, len0);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v2;
+}
+
 /**
  * Convert an arbitrary JSON document to MessagePack bytes (a `Uint8Array` in JS).
  * @param {string} json
@@ -284,11 +327,11 @@ export function msgpack_to_json(data) {
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
-        __wbg_Error_bce6d499ff0a4aff: function(arg0, arg1) {
+        __wbg_Error_92b29b0548f8b746: function(arg0, arg1) {
             const ret = Error(getStringFromWasm0(arg0, arg1));
             return ret;
         },
-        __wbg___wbindgen_throw_9c31b086c2b26051: function(arg0, arg1) {
+        __wbg___wbindgen_throw_344f42d3211c4765: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
         __wbindgen_init_externref_table: function() {

package/dist/pkg/transports_bg.wasm.d.ts

@@ -1,20 +1,22 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
-export const diff: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const __wbg_store_free: (a: number, b: number) => void;
 export const apply: (a: number, b: number, c: number, d: number) => [number, number, number, number];
-export const encode: (a: number, b: number) => [number, number, number, number];
+export const cbor_to_json: (a: number, b: number) => [number, number, number, number];
 export const decode: (a: number, b: number) => [number, number, number, number];
-export const encode_as: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const decode_as: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const diff: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const encode: (a: number, b: number) => [number, number, number, number];
+export const encode_as: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const json_to_cbor: (a: number, b: number) => [number, number, number, number];
 export const json_to_msgpack: (a: number, b: number) => [number, number, number, number];
 export const msgpack_to_json: (a: number, b: number) => [number, number, number, number];
-export const __wbg_store_free: (a: number, b: number) => void;
-export const store_new: () => number;
+export const store_apply: (a: number, b: bigint, c: number, d: number) => [number, number, number];
 export const store_host: (a: number, b: number, c: number, d: number, e: number) => [bigint, number, number];
-export const store_snapshot: (a: number, b: bigint) => [number, number];
 export const store_mutate: (a: number, b: bigint, c: number, d: number) => [number, number, number, number];
-export const store_apply: (a: number, b: bigint, c: number, d: number) => [number, number, number];
+export const store_new: () => number;
+export const store_snapshot: (a: number, b: bigint) => [number, number];
 export const __wbindgen_externrefs: WebAssembly.Table;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@1kbgz/transports",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Generic communication library",
-  "repository": "git@github.com:1kbgz/transports.git",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:1kbgz/transports.git"
+  },
   "author": "1kbgz <dev@1kbgz.com>",
   "license": "Apache-2.0",
   "type": "module",
@@ -25,29 +28,30 @@
     "access": "public"
   },
   "devDependencies": {
-    "@playwright/test": "^1.60.0",
+    "@playwright/test": "^1.62.0",
     "cpy": "^13.2.2",
-    "esbuild": "^0.28.0",
-    "lightningcss": "^1.29.3",
+    "esbuild": "^0.28.1",
+    "lightningcss": "^1.33.0",
     "http-server": "^14.1.1",
     "nodemon": "^3.1.14",
     "npm-run-all": "^4.1.5",
-    "prettier": "^3.8.3",
-    "typescript": "^6.0.3"
+    "oxfmt": "^0.63.0",
+    "oxlint": "^1.78.0",
+    "typescript": "^7.0.2"
   },
   "scripts": {
-    "setup": "cargo install -f wasm-bindgen-cli --version 0.2.121 --locked",
+    "setup": "cargo install -f wasm-bindgen-cli --version 0.2.126 --locked",
     "build:debug": "node build.mjs --debug",
-    "build:rust": "cargo build --release --all-features --target wasm32-unknown-unknown",
+    "build:rust": "cargo build --release --all-features --target wasm32-unknown-unknown --target-dir ../target",
     "build:wasm-bindgen": "wasm-bindgen ../target/wasm32-unknown-unknown/release/transports.wasm --out-dir ./dist/pkg --target web",
     "build:prod": "node build.mjs",
     "build": "npm-run-all build:rust build:wasm-bindgen build:prod",
     "clean": "rm -rf dist lib playwright-report ../transports/extension",
     "dev": "npm-run-all -p start watch",
-    "lint:js": "prettier --check \"src/**/*.{js,ts,jsx,tsx,css}\" \"tests/**/*.{js,ts,jsx,tsx}\" \"*.mjs\" \"*.json\"",
+    "lint:js": "oxlint . && oxfmt --check \"src/**/*.{js,ts,jsx,tsx,css}\" \"tests/**/*.{js,ts,jsx,tsx}\" \"*.mjs\" \"*.json\"",
     "lint:rust": "cargo clippy --all-features && cargo fmt --all -- --check",
     "lint": "npm-run-all lint:*",
-    "fix:js": "prettier  --write \"src/**/*.{js,ts,jsx,tsx,css}\" \"tests/**/*.{js,ts,jsx,tsx}\" \"*.mjs\" \"*.json\"",
+    "fix:js": "oxlint --fix . && oxfmt --write \"src/**/*.{js,ts,jsx,tsx,css}\" \"tests/**/*.{js,ts,jsx,tsx}\" \"*.mjs\" \"*.json\"",
     "fix:rust": "cargo fmt --all",
     "fix": "npm-run-all fix:*",
     "preinstall": "npx only-allow pnpm",

package/dist/html/index.html

@@ -1,13 +0,0 @@
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>transports</title>
-    <meta name="description" content="Generic communication library" />
-    <meta name="author" content="1kbgz" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
-    <link rel="stylesheet" type="text/css" href="css/index.css" />
-    <script type="module" src="cdn/index.js"></script>
-  </head>
-  <body></body>
-</html>