@parity/truapi 0.1.0

package/dist/scale.js

@@ -0,0 +1,121 @@
+/** SCALE codec primitives used by the generated client.
+ *
+ * Thin wrapper over `scale-ts`: re-exports its primitives and combinators,
+ * plus the Polkadot-flavour helpers it does not ship (hex-encoded bytes,
+ * lazy recursive codecs, and `V<N>`-indexed tagged unions).
+ */
+import { Bytes, Enum, createCodec, createDecoder, enhanceCodec, u8, } from "scale-ts";
+export { Enum, Option, Result, Struct, Tuple, Vector, _void, bool, i8, i16, i32, i64, i128, str, u8, u16, u32, u64, u128, } from "scale-ts";
+/** Assert that a string is a valid hex string (`0x...`). */
+export function toHexString(value) {
+    if (!value.startsWith("0x")) {
+        throw new Error(`Expected hex string starting with 0x, got: ${value.slice(0, 20)}`);
+    }
+    return value;
+}
+/** Encode a byte array as a lower-case hex string with a `0x` prefix. */
+export function bytesToHex(bytes) {
+    let hex = "0x";
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+/** Decode a hex string into a byte array. Tolerates a missing `0x` prefix. */
+export function hexToBytes(hex) {
+    const start = hex.startsWith("0x") ? 2 : 0;
+    const length = (hex.length - start) >> 1;
+    const bytes = new Uint8Array(length);
+    for (let i = 0; i < length; i++) {
+        bytes[i] = parseInt(hex.substring(start + i * 2, start + i * 2 + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * SCALE codec for hex-encoded byte strings.
+ *
+ * Encode accepts a `0x`-prefixed hex string and emits SCALE bytes; decode
+ * returns the bytes as a hex string. Pass `length` for fixed-size byte arrays
+ * (`[u8; N]`); omit it for variable-length byte vectors (`Vec<u8>`).
+ */
+export function Hex(length) {
+    return enhanceCodec(Bytes(length), hexToBytes, bytesToHex);
+}
+/**
+ * Same wire format as `scale-ts`'s `Enum`, but exposes `value` as optional in
+ * the public TS type when the variant codec is `Codec<undefined>`. Lets unit
+ * variants of mixed enums round-trip as `{ tag: "X" }` (no `value` key).
+ */
+export function TaggedUnion(inner) {
+    return Enum(inner);
+}
+/**
+ * Enum without payloads — maps string labels to SCALE discriminant bytes.
+ *
+ * `scale-ts` models `Enum({ Foo: _void, Bar: _void })` as tagged objects. For
+ * user-facing TrUAPI enums with only unit variants, we keep the public TS shape
+ * as a plain string union instead.
+ */
+export function Status(...variants) {
+    return enhanceCodec(u8, (value) => {
+        const index = variants.indexOf(value);
+        if (index === -1) {
+            throw new Error(`Unknown status value: ${String(value)}`);
+        }
+        return index;
+    }, (index) => {
+        const value = variants[index];
+        if (value === undefined) {
+            throw new Error(`Unknown status index: ${index}`);
+        }
+        return value;
+    });
+}
+/**
+ * Defers codec construction until first use so recursive generated codecs can
+ * reference each other safely.
+ */
+export function lazy(factory) {
+    let resolved;
+    const get = () => (resolved ??= factory());
+    return createCodec((value) => get().enc(value), (input) => get().dec(input));
+}
+/**
+ * Builds a tagged union codec with explicit SCALE discriminants.
+ *
+ * `scale-ts` assigns enum indexes by object key order. TrUAPI versioned enums pin
+ * `V<N>` to index `N - 1`, including V2-only enums, so generated codecs use this
+ * helper for versioned wire wrappers.
+ */
+export function indexedTaggedUnion(variants) {
+    const byIndex = new Map();
+    for (const [tag, [index, codec]] of Object.entries(variants)) {
+        if (!Number.isInteger(index) || index < 0 || index > 255) {
+            throw new Error(`Invalid enum discriminant for ${tag}: ${index}`);
+        }
+        if (byIndex.has(index)) {
+            throw new Error(`Duplicate enum discriminant: ${index}`);
+        }
+        byIndex.set(index, [tag, codec]);
+    }
+    return createCodec((value) => {
+        const variant = variants[value.tag];
+        if (!variant) {
+            throw new Error(`Unknown enum variant: ${value.tag}`);
+        }
+        const [index, codec] = variant;
+        const payload = codec.enc(value.value);
+        const out = new Uint8Array(payload.length + 1);
+        out[0] = index;
+        out.set(payload, 1);
+        return out;
+    }, createDecoder((input) => {
+        const index = u8.dec(input);
+        const variant = byIndex.get(index);
+        if (!variant) {
+            throw new Error(`Unknown enum discriminant: ${index}`);
+        }
+        const [tag, codec] = variant;
+        return { tag, value: codec.dec(input) };
+    }));
+}

package/dist/transport.d.ts

@@ -0,0 +1,237 @@
+import { type Result } from "neverthrow";
+/**
+ * Handle returned by TrUAPI subscription APIs.
+ **/
+export interface Subscription {
+    /**
+     * Stop the subscription. Calling this more than once has no additional effect.
+     **/
+    unsubscribe: () => void;
+    /**
+     * Transport-assigned request id for the subscription start frame.
+     *
+     * Methods that accept a `followSubscriptionId` use this value to scope
+     * follow-up requests to a specific active subscription.
+     **/
+    subscriptionId: string;
+}
+/**
+ * Terminal error delivered through `Observer.error` for every non-normal
+ * subscription end. When the peer interrupted the stream with a typed payload,
+ * `reason` carries the decoded `Reason`; otherwise `reason` is `undefined` and
+ * the underlying transport/decode error is preserved on `cause`.
+ *
+ * Discriminate with `error.reason !== undefined` (or `'reason' in error`).
+ **/
+export declare class SubscriptionError<Reason = never> extends Error {
+    /**
+     * Typed payload supplied by the peer when it interrupted the subscription.
+     * `undefined` when the stream ended for any other reason (transport close,
+     * decode failure, malformed interrupt payload).
+     **/
+    readonly reason?: Reason;
+    constructor(message: string, options?: {
+        reason?: Reason;
+        cause?: unknown;
+    });
+}
+/**
+ * Minimal Observable-compatible observer shape used by generated subscription
+ * APIs without depending on RxJS.
+ *
+ * `Reason` is the typed interrupt payload for the originating subscription.
+ * Methods without a typed interrupt resolve `Reason` to `never`, leaving
+ * `error.reason` typed as `undefined`.
+ **/
+export interface Observer<Item, Reason = never> {
+    /**
+     * Called with each successfully decoded subscription item.
+     **/
+    next(value: Item): void;
+    /**
+     * Called once when the stream terminates with an error. Inspect
+     * `error.reason` to distinguish a typed peer interrupt from a transport or
+     * decode failure (`error.cause` carries the underlying failure in the
+     * latter case).
+     **/
+    error(error: SubscriptionError<Reason>): void;
+    /**
+     * Called once when the peer normally completes the stream.
+     **/
+    complete(): void;
+}
+/**
+ * Minimal Observable-compatible object returned by generated subscription APIs.
+ **/
+export interface ObservableLike<Item, Reason = never> {
+    /**
+     * Start the stream and receive `next`, `error`, and `complete` callbacks.
+     **/
+    subscribe(observer?: Partial<Observer<Item, Reason>>): Subscription;
+}
+/**
+ * Numeric frame ids for a one-shot request method.
+ **/
+export interface RequestFrameIds {
+    /**
+     * Wire discriminant for the outbound request frame.
+     **/
+    request: number;
+    /**
+     * Wire discriminant for the inbound response frame.
+     **/
+    response: number;
+}
+/**
+ * Numeric frame ids for a subscription method.
+ **/
+export interface SubscriptionFrameIds {
+    /**
+     * Wire discriminant for the outbound start frame.
+     **/
+    start: number;
+    /**
+     * Wire discriminant for the outbound stop frame.
+     **/
+    stop: number;
+    /**
+     * Wire discriminant for the inbound interrupt frame.
+     **/
+    interrupt: number;
+    /**
+     * Wire discriminant for the inbound receive frame.
+     **/
+    receive: number;
+}
+/**
+ * Options accepted by `TrUApiTransport.request`.
+ **/
+export interface RequestParams<Response> {
+    /**
+     * Wire discriminants for this request method.
+     **/
+    ids: RequestFrameIds;
+    /**
+     * SCALE-encoded request payload bytes.
+     **/
+    payload: Uint8Array;
+    /**
+     * Decode SCALE response payload bytes into the generated client return type.
+     **/
+    decodeResponse: (payload: Uint8Array) => Response;
+}
+/**
+ * Options accepted by `TrUApiTransport.subscribeRaw`.
+ **/
+export interface SubscribeRawParams {
+    /**
+     * Wire discriminants for this subscription method.
+     **/
+    ids: SubscriptionFrameIds;
+    /**
+     * SCALE-encoded subscription start payload bytes.
+     **/
+    payload: Uint8Array;
+    /**
+     * Called with raw SCALE receive payload bytes.
+     **/
+    onReceive: (payload: Uint8Array) => void;
+    /**
+     * Called with raw SCALE interrupt payload bytes when the peer interrupts the subscription.
+     **/
+    onInterrupt?: (payload: Uint8Array) => void;
+    /**
+     * Called when the underlying provider closes while the subscription is active.
+     **/
+    onClose?: (error: Error) => void;
+}
+/**
+ * Byte-level transport used by generated client stubs.
+ **/
+export interface TrUApiTransport {
+    /**
+     * Highest TrUAPI protocol version supported by this generated client.
+     **/
+    readonly truapiVersion: number;
+    /**
+     * SCALE codec version negotiated through the handshake.
+     **/
+    readonly codecVersion: number;
+    /**
+     * Send a one-shot request and resolve with the decoded response payload.
+     **/
+    request<Response>(params: RequestParams<Response>): Promise<Response>;
+    /**
+     * Start a subscription and return a handle that can stop it.
+     **/
+    subscribeRaw(params: SubscribeRawParams): Subscription;
+    /**
+     * Tear down the transport and release the listeners it registered on the
+     * underlying `Provider`. Pending requests reject and live subscriptions
+     * receive `onClose`. Idempotent.
+     *
+     * The provider itself is left alone; the caller decides whether to also
+     * call `provider.dispose()` (long-lived hosts that swap providers will
+     * typically dispose the transport but keep the provider).
+     **/
+    dispose(): void;
+}
+/**
+ * Tagged payload inside a TrUAPI wire frame.
+ **/
+export interface Payload {
+    /**
+     * Wire-table numeric discriminant.
+     **/
+    id: number;
+    /**
+     * SCALE-encoded payload body.
+     **/
+    value: Uint8Array;
+}
+/**
+ * Top-level TrUAPI wire message.
+ **/
+export interface ProtocolMessage {
+    /**
+     * Request id used to correlate request/response and subscription frames.
+     **/
+    requestId: string;
+    /**
+     * Tagged SCALE payload carried by this frame.
+     **/
+    payload: Payload;
+}
+/**
+ * Raw message pipe abstraction used by the transport.
+ **/
+export interface Provider {
+    /**
+     * Send a complete SCALE-encoded wire frame to the peer.
+     **/
+    postMessage(message: Uint8Array): void;
+    /**
+     * Register a callback for inbound SCALE-encoded wire frames.
+     **/
+    subscribe(callback: (message: Uint8Array) => void): () => void;
+    /**
+     * Register a callback for provider-level close or failure events.
+     **/
+    subscribeClose?(callback: (error: Error) => void): () => void;
+    /**
+     * Release provider resources and close the underlying pipe.
+     **/
+    dispose(): void;
+}
+/**
+ * Encode a `ProtocolMessage` into a SCALE wire frame.
+ **/
+export declare function encodeWireMessage(message: ProtocolMessage): Result<Uint8Array, Error>;
+/**
+ * Decode a SCALE wire frame into a `ProtocolMessage`.
+ **/
+export declare function decodeWireMessage(message: Uint8Array): Result<ProtocolMessage, Error>;
+/**
+ * Create a provider from a web or Electron `MessagePort`.
+ **/
+export declare function createMessagePortProvider(port: MessagePort | Promise<MessagePort>): Provider;

package/dist/transport.js

@@ -0,0 +1,238 @@
+import { err, ok } from "neverthrow";
+import { str, u8 } from "./scale.js";
+/**
+ * Terminal error delivered through `Observer.error` for every non-normal
+ * subscription end. When the peer interrupted the stream with a typed payload,
+ * `reason` carries the decoded `Reason`; otherwise `reason` is `undefined` and
+ * the underlying transport/decode error is preserved on `cause`.
+ *
+ * Discriminate with `error.reason !== undefined` (or `'reason' in error`).
+ **/
+export class SubscriptionError extends Error {
+    /**
+     * Typed payload supplied by the peer when it interrupted the subscription.
+     * `undefined` when the stream ended for any other reason (transport close,
+     * decode failure, malformed interrupt payload).
+     **/
+    reason;
+    constructor(message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "SubscriptionError";
+        if (options?.reason !== undefined)
+            this.reason = options.reason;
+    }
+}
+/**
+ * Concatenate byte arrays without mutating the source arrays.
+ **/
+function concatBytes(parts) {
+    let total = 0;
+    for (const p of parts)
+        total += p.length;
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+/**
+ * Encode a `ProtocolMessage` into a SCALE wire frame.
+ **/
+export function encodeWireMessage(message) {
+    const id = message.payload.id;
+    if (!Number.isInteger(id) || id < 0 || id > 255) {
+        return err(new Error(`Invalid wire discriminant: ${id}`));
+    }
+    return ok(concatBytes([
+        str.enc(message.requestId),
+        u8.enc(id),
+        message.payload.value,
+    ]));
+}
+/**
+ * Decode a SCALE wire frame into a `ProtocolMessage`.
+ **/
+export function decodeWireMessage(message) {
+    if (message.length < 1) {
+        return err(new Error("Wire frame too short: empty buffer"));
+    }
+    let cursor = message;
+    const requestIdEndResult = scanStrEnd(cursor);
+    if (requestIdEndResult.isErr()) {
+        return err(requestIdEndResult.error);
+    }
+    const requestIdEnd = requestIdEndResult.value;
+    const requestId = str.dec(cursor.subarray(0, requestIdEnd));
+    cursor = cursor.subarray(requestIdEnd);
+    if (cursor.length < 1) {
+        return err(new Error("Wire frame too short: missing discriminant byte"));
+    }
+    const id = cursor[0];
+    const value = cursor.subarray(1);
+    // Hand the value bytes back as a fresh slice so callers may safely retain
+    // it even if the source buffer is reused by the transport.
+    const valueCopy = new Uint8Array(value.length);
+    valueCopy.set(value);
+    return ok({ requestId, payload: { id, value: valueCopy } });
+}
+/**
+ * Return the byte offset just past the leading SCALE-encoded string.
+ **/
+function scanStrEnd(bytes) {
+    if (bytes.length < 1) {
+        return err(new Error("compact-len: empty buffer"));
+    }
+    const first = bytes[0];
+    const mode = first & 0b11;
+    let lengthLen;
+    let strLen;
+    if (mode === 0) {
+        lengthLen = 1;
+        strLen = first >> 2;
+    }
+    else if (mode === 1) {
+        if (bytes.length < 2) {
+            return err(new Error("compact-len: truncated mode-1 prefix"));
+        }
+        lengthLen = 2;
+        strLen = ((first >> 2) | (bytes[1] << 6)) & 0x3fff;
+    }
+    else if (mode === 2) {
+        if (bytes.length < 4) {
+            return err(new Error("compact-len: truncated mode-2 prefix"));
+        }
+        lengthLen = 4;
+        strLen =
+            ((first >> 2) | (bytes[1] << 6) | (bytes[2] << 14) | (bytes[3] << 22)) >>>
+                0;
+    }
+    else {
+        // big-int mode: not used for requestId in our protocol
+        return err(new Error("compact big-int mode not supported in wire envelope"));
+    }
+    const total = lengthLen + strLen;
+    if (total > bytes.length) {
+        return err(new Error("compact-len: declared length exceeds buffer"));
+    }
+    return ok(total);
+}
+/**
+ * Create a provider from a web or Electron `MessagePort`.
+ **/
+export function createMessagePortProvider(port) {
+    let resolvedPort = null;
+    let closedError = null;
+    const pending = [];
+    const listeners = [];
+    const closeListeners = [];
+    /**
+     * Notify close listeners once and drop queued outbound messages.
+     **/
+    function notifyClose(error) {
+        const nextError = error instanceof Error ? error : new Error(String(error));
+        if (closedError) {
+            return;
+        }
+        closedError = nextError;
+        pending.length = 0;
+        for (const listener of [...closeListeners]) {
+            listener(nextError);
+        }
+    }
+    void Promise.resolve(port)
+        .then((p) => {
+        if (closedError) {
+            try {
+                p.close();
+            }
+            catch {
+                // ignore duplicate close during shutdown
+            }
+            return;
+        }
+        resolvedPort = p;
+        p.onmessage = (event) => {
+            const data = event.data;
+            if (!(data instanceof Uint8Array))
+                return;
+            for (const listener of [...listeners])
+                listener(data);
+        };
+        if ("onmessageerror" in p) {
+            p.onmessageerror = () => {
+                notifyClose(new Error("message port closed unexpectedly"));
+            };
+        }
+        p.start();
+        for (const msg of pending)
+            p.postMessage(msg);
+        pending.length = 0;
+    })
+        .catch((error) => {
+        notifyClose(error);
+    });
+    return {
+        /**
+         * Send bytes through the resolved port or queue them until it resolves.
+         **/
+        postMessage(message) {
+            if (closedError) {
+                throw closedError;
+            }
+            if (resolvedPort) {
+                try {
+                    resolvedPort.postMessage(message);
+                }
+                catch (error) {
+                    notifyClose(error);
+                    throw error instanceof Error ? error : new Error(String(error));
+                }
+            }
+            else {
+                pending.push(message);
+            }
+        },
+        /**
+         * Register an inbound message listener.
+         **/
+        subscribe(callback) {
+            listeners.push(callback);
+            return () => {
+                const idx = listeners.indexOf(callback);
+                if (idx >= 0)
+                    listeners.splice(idx, 1);
+            };
+        },
+        /**
+         * Register a close listener.
+         **/
+        subscribeClose(callback) {
+            if (closedError) {
+                callback(closedError);
+                return () => { };
+            }
+            closeListeners.push(callback);
+            return () => {
+                const idx = closeListeners.indexOf(callback);
+                if (idx >= 0)
+                    closeListeners.splice(idx, 1);
+            };
+        },
+        /**
+         * Dispose the provider and close the port if it has resolved.
+         **/
+        dispose() {
+            notifyClose(new Error("message port provider disposed"));
+            try {
+                resolvedPort?.close();
+            }
+            catch {
+                // ignore duplicate close during shutdown
+            }
+            listeners.length = 0;
+            closeListeners.length = 0;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@parity/truapi",
+  "version": "0.1.0",
+  "description": "TrUAPI TypeScript transport, SCALE codecs, and generated API client",
+  "license": "MIT",
+  "author": "Parity Technologies <admin@parity.io>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paritytech/truapi.git",
+    "directory": "js/packages/truapi"
+  },
+  "homepage": "https://github.com/paritytech/truapi#readme",
+  "bugs": {
+    "url": "https://github.com/paritytech/truapi/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./playground/services": {
+      "types": "./dist/playground/codegen/services.d.ts",
+      "import": "./dist/playground/codegen/services.js"
+    },
+    "./playground/services-types": {
+      "types": "./dist/playground/services-types.d.ts",
+      "import": "./dist/playground/services-types.js"
+    }
+  },
+  "scripts": {
+    "ensure-generated": "./scripts/ensure-generated.sh",
+    "build": "tsc",
+    "prebuild": "npm run ensure-generated",
+    "prepare": "npm run build",
+    "codegen": "cargo run -p truapi-codegen -- --input ../../../target/doc/truapi.json --output src/generated --playground-output src/playground --client-examples-output test/generated/examples",
+    "typecheck": "npm run build && npm run typecheck:examples",
+    "pretypecheck:examples": "npm run ensure-generated",
+    "typecheck:examples": "tsc -p tsconfig.examples.json",
+    "pretest": "npm run ensure-generated",
+    "test": "for f in test/*.test.mjs; do echo \"=== $f ===\" && bun \"$f\" || exit 1; done"
+  },
+  "devDependencies": {
+    "typescript": "^5.7"
+  },
+  "dependencies": {
+    "neverthrow": "^8.2.0",
+    "scale-ts": "^1.6.1"
+  }
+}