@neutron-build/nucleus 0.1.0

package/dist/streams/index.js

@@ -0,0 +1,83 @@
+// ---------------------------------------------------------------------------
+// @neutron/nucleus/streams — Streams model plugin (Redis Streams-compatible)
+// ---------------------------------------------------------------------------
+import { requireNucleus } from '../helpers.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class StreamsModelImpl {
+    transport;
+    features;
+    constructor(transport, features) {
+        this.transport = transport;
+        this.features = features;
+    }
+    require() {
+        requireNucleus(this.features, 'Streams');
+    }
+    async xadd(stream, fields) {
+        this.require();
+        // Build variadic args: stream, k1, v1, k2, v2, ...
+        const args = [stream];
+        for (const [k, v] of Object.entries(fields)) {
+            args.push(k, v);
+        }
+        const placeholders = args.map((_, i) => `$${i + 1}`).join(', ');
+        const sql = `SELECT STREAM_XADD(${placeholders})`;
+        return (await this.transport.fetchval(sql, args)) ?? '';
+    }
+    async xlen(stream) {
+        this.require();
+        return (await this.transport.fetchval('SELECT STREAM_XLEN($1)', [stream])) ?? 0;
+    }
+    async xrange(stream, startMs, endMs, count) {
+        this.require();
+        const raw = await this.transport.fetchval('SELECT STREAM_XRANGE($1, $2, $3, $4)', [
+            stream, startMs, endMs, count,
+        ]);
+        if (!raw)
+            return [];
+        return JSON.parse(raw);
+    }
+    async xread(stream, lastIdMs, count) {
+        this.require();
+        const raw = await this.transport.fetchval('SELECT STREAM_XREAD($1, $2, $3)', [
+            stream, lastIdMs, count,
+        ]);
+        if (!raw)
+            return [];
+        return JSON.parse(raw);
+    }
+    async xgroupCreate(stream, group, startId) {
+        this.require();
+        return ((await this.transport.fetchval('SELECT STREAM_XGROUP_CREATE($1, $2, $3)', [
+            stream, group, startId,
+        ])) ?? false);
+    }
+    async xreadGroup(stream, group, consumer, count) {
+        this.require();
+        const raw = await this.transport.fetchval('SELECT STREAM_XREADGROUP($1, $2, $3, $4)', [
+            stream, group, consumer, count,
+        ]);
+        if (!raw)
+            return [];
+        return JSON.parse(raw);
+    }
+    async xack(stream, group, idMs, idSeq) {
+        this.require();
+        return ((await this.transport.fetchval('SELECT STREAM_XACK($1, $2, $3, $4)', [
+            stream, group, idMs, idSeq,
+        ])) ?? false);
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/** Plugin: adds `.streams` to the client. */
+export const withStreams = {
+    name: 'streams',
+    init(transport, features) {
+        return { streams: new StreamsModelImpl(transport, features) };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/streams/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/streams/index.ts"],"names":[],"mappings":"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"}

package/dist/timeseries/index.d.ts

@@ -0,0 +1,46 @@
+import type { NucleusPlugin } from '../types.js';
+export interface TimeSeriesPoint {
+    timestamp: Date;
+    value: number;
+    tags?: Record<string, string>;
+}
+export type AggFunc = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'first' | 'last';
+export type BucketInterval = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month';
+export interface TimeSeriesQueryOptions {
+    /** Filter by tags. */
+    tags?: Record<string, string>;
+    /** Downsample into buckets. */
+    downsample?: {
+        /** Bucket interval name. */
+        interval: BucketInterval;
+        /** Aggregation function. */
+        fn: AggFunc;
+    };
+}
+export interface TimeSeriesModel {
+    /** Write data points to a measurement (series). */
+    write(measurement: string, points: TimeSeriesPoint[]): Promise<void>;
+    /** Return the most recent value for a series. */
+    last(measurement: string): Promise<number | null>;
+    /** Return the total number of data points. */
+    count(measurement: string): Promise<number>;
+    /** Count data points in a time range. */
+    rangeCount(measurement: string, from: Date, to: Date): Promise<number>;
+    /** Average value in a time range. */
+    rangeAvg(measurement: string, from: Date, to: Date): Promise<number | null>;
+    /** Set the data retention period (in days). */
+    retention(measurement: string, days: number): Promise<boolean>;
+    /** Match series names against a pattern. */
+    match(measurement: string, pattern: string): Promise<string>;
+    /** Truncate a timestamp to a bucket boundary. */
+    timeBucket(interval: BucketInterval, timestamp: Date): Promise<number>;
+    /** Query raw data points in a time range. */
+    query(measurement: string, from: Date, to: Date, opts?: TimeSeriesQueryOptions): Promise<TimeSeriesPoint[]>;
+    /** Aggregate data points into time buckets. */
+    aggregate(measurement: string, from: Date, to: Date, interval: BucketInterval, fn: AggFunc): Promise<TimeSeriesPoint[]>;
+}
+/** Plugin: adds `.timeseries` to the client. */
+export declare const withTimeSeries: NucleusPlugin<{
+    timeseries: TimeSeriesModel;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/timeseries/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/timeseries/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,aAAa,EAAmB,MAAM,aAAa,CAAC;AAO7E,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,IAAI,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAEjF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAErF,MAAM,WAAW,sBAAsB;IACrC,sBAAsB;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,+BAA+B;IAC/B,UAAU,CAAC,EAAE;QACX,4BAA4B;QAC5B,QAAQ,EAAE,cAAc,CAAC;QACzB,4BAA4B;QAC5B,EAAE,EAAE,OAAO,CAAC;KACb,CAAC;CACH;AAMD,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE,iDAAiD;IACjD,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAElD,8CAA8C;IAC9C,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C,yCAAyC;IACzC,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEvE,qCAAqC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE5E,+CAA+C;IAC/C,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE/D,4CAA4C;IAC5C,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE7D,iDAAiD;IACjD,UAAU,CAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEvE,6CAA6C;IAC7C,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAE5G,+CAA+C;IAC/C,SAAS,CACP,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,IAAI,EACR,QAAQ,EAAE,cAAc,EACxB,EAAE,EAAE,OAAO,GACV,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CAC/B;AAmJD,gDAAgD;AAChD,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC;IAAE,UAAU,EAAE,eAAe,CAAA;CAAE,CAKzE,CAAC"}

package/dist/timeseries/index.js

@@ -0,0 +1,122 @@
+// ---------------------------------------------------------------------------
+// @neutron/nucleus/timeseries — Time-Series model plugin
+// ---------------------------------------------------------------------------
+import { requireNucleus } from '../helpers.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class TimeSeriesModelImpl {
+    transport;
+    features;
+    constructor(transport, features) {
+        this.transport = transport;
+        this.features = features;
+    }
+    require() {
+        requireNucleus(this.features, 'TimeSeries');
+    }
+    async write(measurement, points) {
+        this.require();
+        for (const p of points) {
+            const tsMs = p.timestamp.getTime();
+            await this.transport.execute('SELECT TS_INSERT($1, $2, $3)', [measurement, tsMs, p.value]);
+        }
+    }
+    async last(measurement) {
+        this.require();
+        return this.transport.fetchval('SELECT TS_LAST($1)', [measurement]);
+    }
+    async count(measurement) {
+        this.require();
+        return (await this.transport.fetchval('SELECT TS_COUNT($1)', [measurement])) ?? 0;
+    }
+    async rangeCount(measurement, from, to) {
+        this.require();
+        return ((await this.transport.fetchval('SELECT TS_RANGE_COUNT($1, $2, $3)', [
+            measurement, from.getTime(), to.getTime(),
+        ])) ?? 0);
+    }
+    async rangeAvg(measurement, from, to) {
+        this.require();
+        return this.transport.fetchval('SELECT TS_RANGE_AVG($1, $2, $3)', [
+            measurement, from.getTime(), to.getTime(),
+        ]);
+    }
+    async retention(measurement, days) {
+        this.require();
+        return (await this.transport.fetchval('SELECT TS_RETENTION($1, $2)', [measurement, days])) ?? false;
+    }
+    async match(measurement, pattern) {
+        this.require();
+        return (await this.transport.fetchval('SELECT TS_MATCH($1, $2)', [measurement, pattern])) ?? '';
+    }
+    async timeBucket(interval, timestamp) {
+        this.require();
+        return ((await this.transport.fetchval('SELECT TIME_BUCKET($1, $2)', [interval, timestamp.getTime()])) ?? 0);
+    }
+    async query(measurement, from, to, opts = {}) {
+        this.require();
+        // Delegate to aggregate if downsample is requested
+        if (opts.downsample) {
+            return this.aggregate(measurement, from, to, opts.downsample.interval, opts.downsample.fn);
+        }
+        const fromMs = from.getTime();
+        const toMs = to.getTime();
+        let sql;
+        let params;
+        if (opts.tags && Object.keys(opts.tags).length > 0) {
+            const tagsJson = JSON.stringify(opts.tags);
+            sql =
+                `SELECT COALESCE((SELECT json_agg(row_to_json(t)) FROM (` +
+                    `SELECT timestamp_ms, value FROM ts_data WHERE series = $1 AND timestamp_ms >= $2 AND timestamp_ms <= $3 AND tags @> $4::jsonb ORDER BY timestamp_ms` +
+                    `) t), '[]')`;
+            params = [measurement, fromMs, toMs, tagsJson];
+        }
+        else {
+            sql =
+                `SELECT COALESCE((SELECT json_agg(row_to_json(t)) FROM (` +
+                    `SELECT timestamp_ms, value FROM ts_data WHERE series = $1 AND timestamp_ms >= $2 AND timestamp_ms <= $3 ORDER BY timestamp_ms` +
+                    `) t), '[]')`;
+            params = [measurement, fromMs, toMs];
+        }
+        const raw = await this.transport.fetchval(sql, params);
+        if (!raw)
+            return [];
+        const points = JSON.parse(raw);
+        return points.map((p) => ({
+            timestamp: new Date(p.timestamp_ms),
+            value: p.value,
+        }));
+    }
+    async aggregate(measurement, from, to, interval, fn) {
+        this.require();
+        const VALID_AGG_FUNCS = ['sum', 'avg', 'min', 'max', 'count', 'first', 'last'];
+        if (!VALID_AGG_FUNCS.includes(fn)) {
+            throw new Error(`Invalid aggregation function: ${fn}. Must be one of: ${VALID_AGG_FUNCS.join(', ')}`);
+        }
+        const sql = `SELECT COALESCE((SELECT json_agg(row_to_json(t)) FROM (` +
+            `SELECT TIME_BUCKET($1, timestamp_ms) AS bucket_ms, ${fn}(value) AS value ` +
+            `FROM ts_data WHERE series = $2 AND timestamp_ms >= $3 AND timestamp_ms <= $4 ` +
+            `GROUP BY bucket_ms ORDER BY bucket_ms` +
+            `) t), '[]')`;
+        const raw = await this.transport.fetchval(sql, [interval, measurement, from.getTime(), to.getTime()]);
+        if (!raw)
+            return [];
+        const points = JSON.parse(raw);
+        return points.map((p) => ({
+            timestamp: new Date(p.bucket_ms),
+            value: p.value,
+        }));
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/** Plugin: adds `.timeseries` to the client. */
+export const withTimeSeries = {
+    name: 'timeseries',
+    init(transport, features) {
+        return { timeseries: new TimeSeriesModelImpl(transport, features) };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/timeseries/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/timeseries/index.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -0,0 +1,97 @@
+import type { Transport, TransactionTransport, QueryResult, IsolationLevel } from './types.js';
+/** Configuration for the base HTTP transport. */
+export interface TransportConfig {
+    /** Base URL of the Nucleus server. */
+    url: string;
+    /** Extra HTTP headers sent with every request. */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default 30000). */
+    timeout?: number;
+}
+/** Extended configuration for mobile transport with retry, cache, and offline queue. */
+export interface MobileTransportConfig extends TransportConfig {
+    /** Maximum number of retry attempts for failed requests (default 3). */
+    maxRetries?: number;
+    /** Base delay in ms between retries — uses exponential backoff (default 1000). */
+    retryDelay?: number;
+    /** Whether to cache SELECT query results (default true). */
+    cacheEnabled?: boolean;
+    /** Time-to-live for cached entries in ms (default 60000). */
+    cacheTTL?: number;
+    /** Whether to queue writes when the device is offline (default true). */
+    offlineQueueEnabled?: boolean;
+    /** Maximum number of queued offline operations (default 100). */
+    maxQueueSize?: number;
+}
+export declare class HttpTransport implements Transport {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly timeout;
+    constructor(url: string, headers?: Record<string, string>, timeout?: number);
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+    execute(sql: string, params?: unknown[]): Promise<number>;
+    fetchval<T = unknown>(sql: string, params?: unknown[]): Promise<T | null>;
+    beginTransaction(isolationLevel?: IsolationLevel): Promise<TransactionTransport>;
+    close(): Promise<void>;
+    ping(): Promise<void>;
+}
+/**
+ * Transport for mobile (React Native) environments.
+ *
+ * Wraps `HttpTransport` and adds:
+ * - Automatic retry with exponential backoff for transient failures
+ * - In-memory cache for SELECT queries
+ * - Offline write queue that flushes when connectivity is restored
+ */
+export declare class MobileTransport implements Transport {
+    private readonly http;
+    private readonly cache;
+    private readonly cacheTTL;
+    private readonly cacheEnabled;
+    private readonly maxRetries;
+    private readonly retryDelay;
+    private readonly offlineQueueEnabled;
+    private readonly maxQueueSize;
+    private offlineQueue;
+    private isOnline;
+    constructor(config: MobileTransportConfig);
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+    execute(sql: string, params?: unknown[]): Promise<number>;
+    fetchval<T = unknown>(sql: string, params?: unknown[]): Promise<T | null>;
+    beginTransaction(isolationLevel?: IsolationLevel): Promise<TransactionTransport>;
+    close(): Promise<void>;
+    ping(): Promise<void>;
+    /** Clear all cached query results, or only those matching `pattern`. */
+    invalidateCache(pattern?: string): void;
+    /** Number of operations waiting in the offline queue. */
+    get queueSize(): number;
+    private withRetry;
+    private flushQueue;
+}
+/**
+ * Transport for desktop environments where Nucleus is embedded via Tauri.
+ *
+ * Skips HTTP serialization overhead by calling Tauri's IPC `invoke()` directly.
+ * Falls back to the `neutron://` custom protocol when Tauri internals are not
+ * available.
+ */
+export declare class EmbeddedTransport implements Transport {
+    private readonly invoke;
+    constructor();
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+    execute(sql: string, params?: unknown[]): Promise<number>;
+    fetchval<T = unknown>(sql: string, params?: unknown[]): Promise<T | null>;
+    beginTransaction(isolationLevel?: IsolationLevel): Promise<TransactionTransport>;
+    close(): Promise<void>;
+    ping(): Promise<void>;
+}
+/**
+ * Create the best transport for the current platform.
+ *
+ * Detection order:
+ * 1. Desktop with Tauri internals -> `EmbeddedTransport` (IPC, zero serialization overhead)
+ * 2. React Native -> `MobileTransport` (retries, caching, offline queue)
+ * 3. Everything else -> `HttpTransport` (standard fetch)
+ */
+export declare function createTransport(config: MobileTransportConfig): Transport;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}