@net-mesh/sdk 0.19.0

package/dist/node.d.ts

@@ -0,0 +1,120 @@
+/**
+ * NetNode — the main SDK handle.
+ *
+ * Every computer, device, and application is a NetNode.
+ * There are no clients, no servers, no coordinators.
+ */
+import { Net as NapiNet } from '@net-mesh/core';
+import type { NetNodeConfig, Receipt, PollRequest, PollResponseData, Stats, SubscribeOpts, StoredEvent } from './types';
+import { EventStream, TypedEventStream } from './stream';
+import { TypedChannel } from './channel';
+/**
+ * A node on the Net mesh.
+ *
+ * @example
+ * ```typescript
+ * const node = await NetNode.create({ shards: 4 });
+ *
+ * node.emit({ token: 'hello', index: 0 });
+ *
+ * for await (const event of node.subscribe()) {
+ *   console.log(event.raw);
+ * }
+ *
+ * await node.shutdown();
+ * ```
+ */
+export declare class NetNode {
+    private bus;
+    private constructor();
+    /**
+     * Create a new NetNode.
+     */
+    static create(config?: NetNodeConfig): Promise<NetNode>;
+    /**
+     * Create a NetNode from an existing NAPI Net instance.
+     */
+    static fromNapi(bus: NapiNet): NetNode;
+    /**
+     * Emit a typed event (serializes to JSON).
+     */
+    emit(event: object): Receipt | null;
+    /**
+     * Emit a raw JSON string.
+     */
+    emitRaw(json: string): Receipt | null;
+    /**
+     * Emit a raw Buffer (fastest path, zero-copy to Rust).
+     */
+    emitBuffer(data: Buffer): boolean;
+    /**
+     * Emit a batch of typed events. Returns number ingested.
+     */
+    emitBatch(events: object[]): number;
+    /**
+     * Emit a batch of raw JSON strings. Returns number ingested.
+     */
+    emitRawBatch(jsons: string[]): number;
+    /**
+     * Fire-and-forget ingestion (no return value, maximum speed).
+     */
+    fire(json: string): boolean;
+    /**
+     * Fire-and-forget batch ingestion. Returns count ingested.
+     */
+    fireBatch(jsons: string[]): number;
+    /**
+     * One-shot poll for events.
+     */
+    poll(request: PollRequest): Promise<PollResponseData>;
+    /**
+     * Poll a single event (convenience).
+     */
+    pollOne(): Promise<StoredEvent | null>;
+    /**
+     * Subscribe to an async stream of events.
+     *
+     * @example
+     * ```typescript
+     * for await (const event of node.subscribe({ limit: 100 })) {
+     *   console.log(event.raw);
+     * }
+     * ```
+     */
+    subscribe(opts?: SubscribeOpts): EventStream;
+    /**
+     * Subscribe to a typed stream of events.
+     *
+     * Each event is automatically deserialized from JSON.
+     *
+     * @example
+     * ```typescript
+     * for await (const token of node.subscribeTyped<TokenEvent>()) {
+     *   console.log(token.token, token.index);
+     * }
+     * ```
+     */
+    subscribeTyped<T>(opts?: SubscribeOpts): TypedEventStream<T>;
+    /**
+     * Create a typed channel for pub/sub.
+     *
+     * @example
+     * ```typescript
+     * const temps = node.channel<TemperatureReading>('sensors/temperature');
+     * temps.publish({ sensor_id: 'A1', celsius: 22.5, timestamp: Date.now() });
+     * ```
+     */
+    channel<T>(name: string, validator?: (data: unknown) => T): TypedChannel<T>;
+    /** Get ingestion statistics. */
+    stats(): Stats;
+    /** Get the number of active shards. */
+    shards(): number;
+    /** Flush all pending batches to the adapter. */
+    flush(): Promise<void>;
+    /** Gracefully shut down the node. */
+    shutdown(): Promise<void>;
+    /**
+     * Get the underlying NAPI binding (escape hatch).
+     */
+    get napi(): NapiNet;
+}

package/dist/node.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * NetNode — the main SDK handle.
+ *
+ * Every computer, device, and application is a NetNode.
+ * There are no clients, no servers, no coordinators.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetNode = void 0;
+const core_1 = require("@net-mesh/core");
+const stream_1 = require("./stream");
+const channel_1 = require("./channel");
+/**
+ * A node on the Net mesh.
+ *
+ * @example
+ * ```typescript
+ * const node = await NetNode.create({ shards: 4 });
+ *
+ * node.emit({ token: 'hello', index: 0 });
+ *
+ * for await (const event of node.subscribe()) {
+ *   console.log(event.raw);
+ * }
+ *
+ * await node.shutdown();
+ * ```
+ */
+class NetNode {
+    bus;
+    constructor(bus) {
+        this.bus = bus;
+    }
+    /**
+     * Create a new NetNode.
+     */
+    static async create(config = {}) {
+        const options = buildOptions(config);
+        const bus = await core_1.Net.create(options);
+        return new NetNode(bus);
+    }
+    /**
+     * Create a NetNode from an existing NAPI Net instance.
+     */
+    static fromNapi(bus) {
+        return new NetNode(bus);
+    }
+    // ---- Ingestion ----
+    /**
+     * Emit a typed event (serializes to JSON).
+     */
+    emit(event) {
+        const json = JSON.stringify(event);
+        const result = this.bus.ingestRawSync(json);
+        return { shardId: result.shardId, timestamp: result.timestamp };
+    }
+    /**
+     * Emit a raw JSON string.
+     */
+    emitRaw(json) {
+        const result = this.bus.ingestRawSync(json);
+        return { shardId: result.shardId, timestamp: result.timestamp };
+    }
+    /**
+     * Emit a raw Buffer (fastest path, zero-copy to Rust).
+     */
+    emitBuffer(data) {
+        return this.bus.push(data);
+    }
+    /**
+     * Emit a batch of typed events. Returns number ingested.
+     */
+    emitBatch(events) {
+        const jsons = events.map((e) => JSON.stringify(e));
+        return this.bus.ingestRawBatchSync(jsons);
+    }
+    /**
+     * Emit a batch of raw JSON strings. Returns number ingested.
+     */
+    emitRawBatch(jsons) {
+        return this.bus.ingestRawBatchSync(jsons);
+    }
+    /**
+     * Fire-and-forget ingestion (no return value, maximum speed).
+     */
+    fire(json) {
+        return this.bus.ingestFire(json);
+    }
+    /**
+     * Fire-and-forget batch ingestion. Returns count ingested.
+     */
+    fireBatch(jsons) {
+        return this.bus.ingestBatchFire(jsons);
+    }
+    // ---- Consumption ----
+    /**
+     * One-shot poll for events.
+     */
+    async poll(request) {
+        const response = await this.bus.poll({
+            limit: request.limit,
+            cursor: request.cursor,
+            filter: request.filter,
+            ordering: request.ordering,
+        });
+        return {
+            events: response.events.map((e) => ({
+                id: e.id,
+                raw: e.raw,
+                insertionTs: e.insertionTs,
+                shardId: e.shardId,
+            })),
+            nextId: response.nextId ?? undefined,
+            hasMore: response.hasMore,
+        };
+    }
+    /**
+     * Poll a single event (convenience).
+     */
+    async pollOne() {
+        const response = await this.poll({ limit: 1 });
+        return response.events[0] ?? null;
+    }
+    /**
+     * Subscribe to an async stream of events.
+     *
+     * @example
+     * ```typescript
+     * for await (const event of node.subscribe({ limit: 100 })) {
+     *   console.log(event.raw);
+     * }
+     * ```
+     */
+    subscribe(opts) {
+        return new stream_1.EventStream(this.bus, opts);
+    }
+    /**
+     * Subscribe to a typed stream of events.
+     *
+     * Each event is automatically deserialized from JSON.
+     *
+     * @example
+     * ```typescript
+     * for await (const token of node.subscribeTyped<TokenEvent>()) {
+     *   console.log(token.token, token.index);
+     * }
+     * ```
+     */
+    subscribeTyped(opts) {
+        return new stream_1.TypedEventStream(this.bus, opts);
+    }
+    /**
+     * Create a typed channel for pub/sub.
+     *
+     * @example
+     * ```typescript
+     * const temps = node.channel<TemperatureReading>('sensors/temperature');
+     * temps.publish({ sensor_id: 'A1', celsius: 22.5, timestamp: Date.now() });
+     * ```
+     */
+    channel(name, validator) {
+        return new channel_1.TypedChannel(this.bus, name, validator);
+    }
+    // ---- Lifecycle ----
+    /** Get ingestion statistics. */
+    stats() {
+        return this.bus.stats();
+    }
+    /** Get the number of active shards. */
+    shards() {
+        return this.bus.numShards();
+    }
+    /** Flush all pending batches to the adapter. */
+    async flush() {
+        await this.bus.flush();
+    }
+    /** Gracefully shut down the node. */
+    async shutdown() {
+        await this.bus.shutdown();
+    }
+    /**
+     * Get the underlying NAPI binding (escape hatch).
+     */
+    get napi() {
+        return this.bus;
+    }
+}
+exports.NetNode = NetNode;
+/** Convert SDK config to NAPI EventBusOptions. */
+function buildOptions(config) {
+    const options = {};
+    if (config.shards !== undefined)
+        options.numShards = config.shards;
+    if (config.bufferCapacity !== undefined)
+        options.ringBufferCapacity = config.bufferCapacity;
+    if (config.backpressure !== undefined)
+        options.backpressureMode = config.backpressure;
+    if (config.transport) {
+        const t = config.transport;
+        switch (t.type) {
+            case 'memory':
+                // No adapter config — uses noop.
+                break;
+            case 'redis':
+                options.redis = {
+                    url: t.url,
+                    prefix: t.prefix,
+                    pipelineSize: t.pipelineSize,
+                    poolSize: t.poolSize,
+                    connectTimeoutMs: t.connectTimeoutMs,
+                    commandTimeoutMs: t.commandTimeoutMs,
+                    maxStreamLen: t.maxStreamLen,
+                };
+                break;
+            case 'jetstream':
+                options.jetstream = {
+                    url: t.url,
+                    prefix: t.prefix,
+                    connectTimeoutMs: t.connectTimeoutMs,
+                    requestTimeoutMs: t.requestTimeoutMs,
+                    maxMessages: t.maxMessages,
+                    maxBytes: t.maxBytes,
+                    maxAgeMs: t.maxAgeMs,
+                    replicas: t.replicas,
+                };
+                break;
+            case 'mesh':
+                options.net = {
+                    bindAddr: t.bind,
+                    peerAddr: t.peer,
+                    psk: t.psk,
+                    role: t.role ?? 'initiator',
+                    peerPublicKey: t.peerPublicKey,
+                    secretKey: t.secretKey,
+                    publicKey: t.publicKey,
+                    reliability: t.reliability,
+                    heartbeatIntervalMs: t.heartbeatIntervalMs,
+                    sessionTimeoutMs: t.sessionTimeoutMs,
+                    batchedIo: t.batchedIo,
+                    packetPoolSize: t.packetPoolSize,
+                };
+                break;
+        }
+    }
+    return options;
+}

package/dist/redis-dedup.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Redis Streams consumer-side dedup helper — re-export of the NAPI
+ * class from `@net-mesh/core`.
+ *
+ * The Redis adapter writes a stable `dedup_id` field on every XADD
+ * entry — see the producer-side contract in `sdk-ts/README.md`.
+ * The dedup helper filters producer-retry-induced duplicates at
+ * consume time. Default capacity is 4096; production callers should
+ * size to roughly `events_per_sec * dedup_window_seconds`.
+ *
+ * This shim re-exports the underlying NAPI class so users can
+ * `import { RedisStreamDedup } from '@net-mesh/sdk'` directly
+ * instead of reaching into `@net-mesh/core`.
+ *
+ * @example
+ * ```typescript
+ * import { RedisStreamDedup } from '@net-mesh/sdk';
+ * import { createClient } from 'redis';
+ *
+ * // Sizing: ~10k events/sec * 1 min dedup window → ~600,000.
+ * const dedup = new RedisStreamDedup(600_000);
+ *
+ * const r = createClient();
+ * await r.connect();
+ *
+ * let cursor = '0';
+ * while (true) {
+ *   // After the first page, use the exclusive form `(<id>` so we
+ *   // don't re-read the entry the cursor points at.
+ *   const start = cursor === '0' ? cursor : `(${cursor}`;
+ *   const entries = await r.xRange('net:shard:0', start, '+', { COUNT: 100 });
+ *   if (entries.length === 0) break;
+ *   for (const entry of entries) {
+ *     // Advance the cursor BEFORE the duplicate check. Skipping
+ *     // the `cursor = entry.id` assignment on duplicate entries
+ *     // (via `continue`) makes the loop spin forever re-reading
+ *     // the same range when a window is full of duplicates.
+ *     cursor = entry.id;
+ *     const dedupId = entry.message.dedup_id;
+ *     if (dedupId && dedup.isDuplicate(dedupId)) continue;
+ *     await process(entry);
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { RedisStreamDedup } from '@net-mesh/core';

package/dist/redis-dedup.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Redis Streams consumer-side dedup helper — re-export of the NAPI
+ * class from `@net-mesh/core`.
+ *
+ * The Redis adapter writes a stable `dedup_id` field on every XADD
+ * entry — see the producer-side contract in `sdk-ts/README.md`.
+ * The dedup helper filters producer-retry-induced duplicates at
+ * consume time. Default capacity is 4096; production callers should
+ * size to roughly `events_per_sec * dedup_window_seconds`.
+ *
+ * This shim re-exports the underlying NAPI class so users can
+ * `import { RedisStreamDedup } from '@net-mesh/sdk'` directly
+ * instead of reaching into `@net-mesh/core`.
+ *
+ * @example
+ * ```typescript
+ * import { RedisStreamDedup } from '@net-mesh/sdk';
+ * import { createClient } from 'redis';
+ *
+ * // Sizing: ~10k events/sec * 1 min dedup window → ~600,000.
+ * const dedup = new RedisStreamDedup(600_000);
+ *
+ * const r = createClient();
+ * await r.connect();
+ *
+ * let cursor = '0';
+ * while (true) {
+ *   // After the first page, use the exclusive form `(<id>` so we
+ *   // don't re-read the entry the cursor points at.
+ *   const start = cursor === '0' ? cursor : `(${cursor}`;
+ *   const entries = await r.xRange('net:shard:0', start, '+', { COUNT: 100 });
+ *   if (entries.length === 0) break;
+ *   for (const entry of entries) {
+ *     // Advance the cursor BEFORE the duplicate check. Skipping
+ *     // the `cursor = entry.id` assignment on duplicate entries
+ *     // (via `continue`) makes the loop spin forever re-reading
+ *     // the same range when a window is full of duplicates.
+ *     cursor = entry.id;
+ *     const dedupId = entry.message.dedup_id;
+ *     if (dedupId && dedup.isDuplicate(dedupId)) continue;
+ *     await process(entry);
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisStreamDedup = void 0;
+var core_1 = require("@net-mesh/core");
+Object.defineProperty(exports, "RedisStreamDedup", { enumerable: true, get: function () { return core_1.RedisStreamDedup; } });

package/dist/stream.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Async streaming event consumption.
+ */
+import type { Net as NapiNet } from '@net-mesh/core';
+import type { StoredEvent, SubscribeOpts } from './types';
+/**
+ * An async iterable stream of events from the bus.
+ *
+ * Uses adaptive polling — tight loop when events flow, exponential
+ * backoff when idle.
+ *
+ * @example
+ * ```typescript
+ * for await (const event of node.subscribe({ limit: 100 })) {
+ *   console.log(event.raw);
+ * }
+ * ```
+ */
+export declare class EventStream implements AsyncIterable<StoredEvent> {
+    private bus;
+    private opts;
+    private cursor?;
+    private aborted;
+    constructor(bus: NapiNet, opts?: SubscribeOpts);
+    /** Stop the stream. */
+    stop(): void;
+    [Symbol.asyncIterator](): AsyncIterableIterator<StoredEvent>;
+}
+/**
+ * A typed async iterable stream that deserializes events into `T`.
+ *
+ * @example
+ * ```typescript
+ * interface TokenEvent { token: string; index: number; }
+ * for await (const token of node.subscribe<TokenEvent>({ limit: 100 })) {
+ *   console.log(token.token, token.index);
+ * }
+ * ```
+ */
+export declare class TypedEventStream<T> implements AsyncIterable<T> {
+    private inner;
+    private parse;
+    constructor(bus: NapiNet, opts?: SubscribeOpts, parse?: (raw: string) => T);
+    /** Stop the stream. */
+    stop(): void;
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+}

package/dist/stream.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Async streaming event consumption.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypedEventStream = exports.EventStream = void 0;
+// Starting backoff for idle polls and the inter-poll wait on
+// partial-batch responses. `1` would have us re-issue an FFI poll
+// hundreds of times per second on a near-drained stream that returns
+// 1-2 events per call; `5` keeps us at a 200/s ceiling on that path
+// while still feeling instant. Saturated streams (full `limit`
+// batches) skip the sleep entirely and continue to drain at full
+// speed.
+const DEFAULT_POLL_INTERVAL = 5;
+const DEFAULT_MAX_BACKOFF = 100;
+const DEFAULT_LIMIT = 100;
+/**
+ * An async iterable stream of events from the bus.
+ *
+ * Uses adaptive polling — tight loop when events flow, exponential
+ * backoff when idle.
+ *
+ * @example
+ * ```typescript
+ * for await (const event of node.subscribe({ limit: 100 })) {
+ *   console.log(event.raw);
+ * }
+ * ```
+ */
+class EventStream {
+    bus;
+    opts;
+    cursor;
+    aborted = false;
+    constructor(bus, opts = {}) {
+        this.bus = bus;
+        this.opts = {
+            limit: opts.limit ?? DEFAULT_LIMIT,
+            filter: opts.filter ?? '',
+            ordering: opts.ordering ?? 'none',
+            pollIntervalMs: opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL,
+            maxBackoffMs: opts.maxBackoffMs ?? DEFAULT_MAX_BACKOFF,
+        };
+    }
+    /** Stop the stream. */
+    stop() {
+        this.aborted = true;
+    }
+    async *[Symbol.asyncIterator]() {
+        let backoff = this.opts.pollIntervalMs;
+        while (!this.aborted) {
+            const response = await this.bus.poll({
+                limit: this.opts.limit,
+                cursor: this.cursor,
+                filter: this.opts.filter || undefined,
+                ordering: this.opts.ordering,
+            });
+            if (response.events.length > 0) {
+                backoff = this.opts.pollIntervalMs;
+                this.cursor = response.nextId ?? undefined;
+                for (const event of response.events) {
+                    yield {
+                        id: event.id,
+                        raw: event.raw,
+                        insertionTs: event.insertionTs,
+                        shardId: event.shardId,
+                    };
+                }
+                // Partial-batch sleep: a poll that returned fewer than `limit`
+                // events has drained (or nearly drained) the bus; re-issuing
+                // immediately would just spam FFI calls for trickle streams.
+                // A full-batch response means more events are queued, so we
+                // skip the sleep and loop tight to keep up.
+                if (response.events.length < this.opts.limit) {
+                    await sleep(this.opts.pollIntervalMs);
+                }
+            }
+            else {
+                // Exponential backoff when idle.
+                await sleep(backoff);
+                backoff = Math.min(backoff * 2, this.opts.maxBackoffMs);
+            }
+        }
+    }
+}
+exports.EventStream = EventStream;
+/**
+ * A typed async iterable stream that deserializes events into `T`.
+ *
+ * @example
+ * ```typescript
+ * interface TokenEvent { token: string; index: number; }
+ * for await (const token of node.subscribe<TokenEvent>({ limit: 100 })) {
+ *   console.log(token.token, token.index);
+ * }
+ * ```
+ */
+class TypedEventStream {
+    inner;
+    parse;
+    constructor(bus, opts = {}, parse) {
+        this.inner = new EventStream(bus, opts);
+        this.parse = parse ?? ((raw) => JSON.parse(raw));
+    }
+    /** Stop the stream. */
+    stop() {
+        this.inner.stop();
+    }
+    async *[Symbol.asyncIterator]() {
+        for await (const event of this.inner) {
+            yield this.parse(event.raw);
+        }
+    }
+}
+exports.TypedEventStream = TypedEventStream;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}