@neutron-build/nucleus 0.1.0

package/dist/kv/index.js

@@ -0,0 +1,223 @@
+// ---------------------------------------------------------------------------
+// @neutron/nucleus/kv — KV model plugin
+// ---------------------------------------------------------------------------
+import { requireNucleus } from '../helpers.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+function resolveKey(key, namespace) {
+    return namespace ? `${namespace}:${key}` : key;
+}
+class KVModelImpl {
+    transport;
+    features;
+    constructor(transport, features) {
+        this.transport = transport;
+        this.features = features;
+    }
+    require() {
+        requireNucleus(this.features, 'KV');
+    }
+    // -- Base ------------------------------------------------------------------
+    async get(key) {
+        this.require();
+        return this.transport.fetchval('SELECT KV_GET($1)', [key]);
+    }
+    async getTyped(key) {
+        const raw = await this.get(key);
+        if (raw === null)
+            return null;
+        return JSON.parse(raw);
+    }
+    async set(key, value, opts) {
+        this.require();
+        const k = resolveKey(key, opts?.namespace);
+        if (opts?.ttl !== undefined) {
+            await this.transport.execute('SELECT KV_SET($1, $2, $3)', [k, value, opts.ttl]);
+        }
+        else {
+            await this.transport.execute('SELECT KV_SET($1, $2)', [k, value]);
+        }
+    }
+    async setTyped(key, value, opts) {
+        await this.set(key, JSON.stringify(value), opts);
+    }
+    async setNX(key, value) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_SETNX($1, $2)', [key, value])) ?? false;
+    }
+    async delete(key) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_DEL($1)', [key])) ?? false;
+    }
+    async exists(key) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_EXISTS($1)', [key])) ?? false;
+    }
+    async incr(key, amount) {
+        this.require();
+        if (amount !== undefined) {
+            return (await this.transport.fetchval('SELECT KV_INCR($1, $2)', [key, amount])) ?? 0;
+        }
+        return (await this.transport.fetchval('SELECT KV_INCR($1)', [key])) ?? 0;
+    }
+    async ttl(key) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_TTL($1)', [key])) ?? -2;
+    }
+    async expire(key, seconds) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_EXPIRE($1, $2)', [key, seconds])) ?? false;
+    }
+    async dbSize() {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_DBSIZE()')) ?? 0;
+    }
+    async flushDB() {
+        this.require();
+        await this.transport.execute('SELECT KV_FLUSHDB()');
+    }
+    async scan(pattern, count = 100) {
+        this.require();
+        const result = await this.transport.query('SELECT KV_SCAN($1, $2)', [pattern, count]);
+        return result.rows;
+    }
+    // -- Lists -----------------------------------------------------------------
+    async lpush(key, value) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_LPUSH($1, $2)', [key, value])) ?? 0;
+    }
+    async rpush(key, value) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_RPUSH($1, $2)', [key, value])) ?? 0;
+    }
+    async lpop(key) {
+        this.require();
+        return this.transport.fetchval('SELECT KV_LPOP($1)', [key]);
+    }
+    async rpop(key) {
+        this.require();
+        return this.transport.fetchval('SELECT KV_RPOP($1)', [key]);
+    }
+    async lrange(key, start, stop) {
+        this.require();
+        const raw = await this.transport.fetchval('SELECT KV_LRANGE($1, $2, $3)', [key, start, stop]);
+        if (!raw)
+            return [];
+        return raw.split(',');
+    }
+    async llen(key) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_LLEN($1)', [key])) ?? 0;
+    }
+    async lindex(key, index) {
+        this.require();
+        return this.transport.fetchval('SELECT KV_LINDEX($1, $2)', [key, index]);
+    }
+    // -- Hashes ----------------------------------------------------------------
+    async hset(key, field, value) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_HSET($1, $2, $3)', [key, field, value])) ?? false;
+    }
+    async hget(key, field) {
+        this.require();
+        return this.transport.fetchval('SELECT KV_HGET($1, $2)', [key, field]);
+    }
+    async hdel(key, field) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_HDEL($1, $2)', [key, field])) ?? false;
+    }
+    async hexists(key, field) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_HEXISTS($1, $2)', [key, field])) ?? false;
+    }
+    async hgetall(key) {
+        this.require();
+        const raw = await this.transport.fetchval('SELECT KV_HGETALL($1)', [key]);
+        if (!raw)
+            return {};
+        const result = {};
+        for (const pair of raw.split(',')) {
+            const eqIdx = pair.indexOf('=');
+            if (eqIdx !== -1) {
+                result[pair.slice(0, eqIdx)] = pair.slice(eqIdx + 1);
+            }
+        }
+        return result;
+    }
+    async hlen(key) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_HLEN($1)', [key])) ?? 0;
+    }
+    // -- Sets ------------------------------------------------------------------
+    async sadd(key, member) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_SADD($1, $2)', [key, member])) ?? false;
+    }
+    async srem(key, member) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_SREM($1, $2)', [key, member])) ?? false;
+    }
+    async smembers(key) {
+        this.require();
+        const raw = await this.transport.fetchval('SELECT KV_SMEMBERS($1)', [key]);
+        if (!raw)
+            return [];
+        return raw.split(',');
+    }
+    async sismember(key, member) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_SISMEMBER($1, $2)', [key, member])) ?? false;
+    }
+    async scard(key) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_SCARD($1)', [key])) ?? 0;
+    }
+    // -- Sorted Sets -----------------------------------------------------------
+    async zadd(key, score, member) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_ZADD($1, $2, $3)', [key, score, member])) ?? false;
+    }
+    async zrange(key, start, stop) {
+        this.require();
+        const raw = await this.transport.fetchval('SELECT KV_ZRANGE($1, $2, $3)', [key, start, stop]);
+        if (!raw)
+            return [];
+        return raw.split(',');
+    }
+    async zrangeByScore(key, min, max) {
+        this.require();
+        const raw = await this.transport.fetchval('SELECT KV_ZRANGEBYSCORE($1, $2, $3)', [key, min, max]);
+        if (!raw)
+            return [];
+        return raw.split(',');
+    }
+    async zrem(key, member) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_ZREM($1, $2)', [key, member])) ?? false;
+    }
+    async zcard(key) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_ZCARD($1)', [key])) ?? 0;
+    }
+    // -- HyperLogLog -----------------------------------------------------------
+    async pfadd(key, element) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_PFADD($1, $2)', [key, element])) ?? false;
+    }
+    async pfcount(key) {
+        this.require();
+        return (await this.transport.fetchval('SELECT KV_PFCOUNT($1)', [key])) ?? 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/** Plugin: adds `.kv` to the client. */
+export const withKV = {
+    name: 'kv',
+    init(transport, features) {
+        return { kv: new KVModelImpl(transport, features) };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/kv/index.js.map

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

package/dist/migrate.d.ts

@@ -0,0 +1,37 @@
+import type { Transport } from './types.js';
+/** A single migration definition. */
+export interface Migration {
+    /** Monotonically increasing version number. */
+    version: number;
+    /** Human-readable name. */
+    name: string;
+    /** SQL to apply the migration. */
+    up: string;
+    /** SQL to revert the migration (optional). */
+    down?: string;
+}
+/** A migration that has already been applied. */
+export interface MigrationRecord {
+    version: number;
+    name: string;
+    appliedAt: Date;
+}
+/**
+ * Run all pending migrations in ascending version order.
+ *
+ * Each migration runs inside its own transaction. Returns the names of the
+ * migrations that were applied.
+ */
+export declare function migrate(transport: Transport, migrations: Migration[]): Promise<string[]>;
+/**
+ * Roll back the most recently applied migrations.
+ *
+ * @param steps Number of migrations to roll back (default 1).
+ * @returns Names of the migrations that were rolled back.
+ */
+export declare function migrateDown(transport: Transport, migrations: Migration[], steps?: number): Promise<string[]>;
+/**
+ * Return all previously applied migrations, ordered by version ascending.
+ */
+export declare function migrationStatus(transport: Transport): Promise<MigrationRecord[]>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM5C,qCAAqC;AACrC,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,IAAI,CAAC;CACjB;AA2BD;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAwB9F;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,SAAS,EAAE,EACvB,KAAK,SAAI,GACR,OAAO,CAAC,MAAM,EAAE,CAAC,CAyBnB;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAUtF"}

package/dist/migrate.js

@@ -0,0 +1,95 @@
+// ---------------------------------------------------------------------------
+// Nucleus client — migration system
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const MIGRATIONS_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS _neutron_migrations (
+  version     INTEGER PRIMARY KEY,
+  name        TEXT NOT NULL,
+  applied_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+)`;
+async function ensureTable(transport) {
+    await transport.execute(MIGRATIONS_TABLE_SQL);
+}
+async function appliedVersions(transport) {
+    await ensureTable(transport);
+    const result = await transport.query('SELECT version FROM _neutron_migrations');
+    return new Set(result.rows.map((r) => r.version));
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Run all pending migrations in ascending version order.
+ *
+ * Each migration runs inside its own transaction. Returns the names of the
+ * migrations that were applied.
+ */
+export async function migrate(transport, migrations) {
+    const applied = await appliedVersions(transport);
+    const sorted = [...migrations].sort((a, b) => a.version - b.version);
+    const ran = [];
+    for (const m of sorted) {
+        if (applied.has(m.version))
+            continue;
+        const tx = await transport.beginTransaction();
+        try {
+            await tx.execute(m.up);
+            await tx.execute('INSERT INTO _neutron_migrations (version, name) VALUES ($1, $2)', [m.version, m.name]);
+            await tx.commit();
+            ran.push(m.name);
+        }
+        catch (err) {
+            await tx.rollback();
+            throw err;
+        }
+    }
+    return ran;
+}
+/**
+ * Roll back the most recently applied migrations.
+ *
+ * @param steps Number of migrations to roll back (default 1).
+ * @returns Names of the migrations that were rolled back.
+ */
+export async function migrateDown(transport, migrations, steps = 1) {
+    const applied = await appliedVersions(transport);
+    const sorted = [...migrations].sort((a, b) => b.version - a.version); // descending
+    const rolled = [];
+    for (const m of sorted) {
+        if (rolled.length >= steps)
+            break;
+        if (!applied.has(m.version))
+            continue;
+        if (!m.down) {
+            throw new Error(`Migration ${m.version} (${m.name}) has no down SQL`);
+        }
+        const tx = await transport.beginTransaction();
+        try {
+            await tx.execute(m.down);
+            await tx.execute('DELETE FROM _neutron_migrations WHERE version = $1', [m.version]);
+            await tx.commit();
+            rolled.push(m.name);
+        }
+        catch (err) {
+            await tx.rollback();
+            throw err;
+        }
+    }
+    return rolled;
+}
+/**
+ * Return all previously applied migrations, ordered by version ascending.
+ */
+export async function migrationStatus(transport) {
+    await ensureTable(transport);
+    const result = await transport.query('SELECT version, name, applied_at FROM _neutron_migrations ORDER BY version');
+    return result.rows.map((r) => ({
+        version: r.version,
+        name: r.name,
+        appliedAt: new Date(r.applied_at),
+    }));
+}
+//# sourceMappingURL=migrate.js.map

package/dist/migrate.js.map

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

package/dist/pubsub/index.d.ts

@@ -0,0 +1,14 @@
+import type { NucleusPlugin } from '../types.js';
+export interface PubSubModel {
+    /** Publish a message on a channel. Returns the number of subscribers reached. */
+    publish(channel: string, message: string): Promise<number>;
+    /** Return active channels matching an optional pattern (empty = all). */
+    channels(pattern?: string): Promise<string>;
+    /** Return the number of subscribers on a channel. */
+    subscribers(channel: string): Promise<number>;
+}
+/** Plugin: adds `.pubsub` to the client. */
+export declare const withPubSub: NucleusPlugin<{
+    pubsub: PubSubModel;
+}>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pubsub/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,aAAa,EAAmB,MAAM,aAAa,CAAC;AAO7E,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE3D,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C,qDAAqD;IACrD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/C;AAuCD,4CAA4C;AAC5C,eAAO,MAAM,UAAU,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,CAK7D,CAAC"}

package/dist/pubsub/index.js

@@ -0,0 +1,44 @@
+// ---------------------------------------------------------------------------
+// @neutron/nucleus/pubsub — PubSub model plugin
+// ---------------------------------------------------------------------------
+import { requireNucleus } from '../helpers.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class PubSubModelImpl {
+    transport;
+    features;
+    constructor(transport, features) {
+        this.transport = transport;
+        this.features = features;
+    }
+    require() {
+        requireNucleus(this.features, 'PubSub');
+    }
+    async publish(channel, message) {
+        this.require();
+        return (await this.transport.fetchval('SELECT PUBSUB_PUBLISH($1, $2)', [channel, message])) ?? 0;
+    }
+    async channels(pattern) {
+        this.require();
+        if (pattern) {
+            return (await this.transport.fetchval('SELECT PUBSUB_CHANNELS($1)', [pattern])) ?? '';
+        }
+        return (await this.transport.fetchval('SELECT PUBSUB_CHANNELS()')) ?? '';
+    }
+    async subscribers(channel) {
+        this.require();
+        return (await this.transport.fetchval('SELECT PUBSUB_SUBSCRIBERS($1)', [channel])) ?? 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/** Plugin: adds `.pubsub` to the client. */
+export const withPubSub = {
+    name: 'pubsub',
+    init(transport, features) {
+        return { pubsub: new PubSubModelImpl(transport, features) };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/pubsub/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pubsub/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gDAAgD;AAChD,8EAA8E;AAG9E,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAiB/C,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,eAAe;IAEA;IACA;IAFnB,YACmB,SAAoB,EACpB,QAAyB;QADzB,cAAS,GAAT,SAAS,CAAW;QACpB,aAAQ,GAAR,QAAQ,CAAiB;IACzC,CAAC;IAEI,OAAO;QACb,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAe,EAAE,OAAe;QAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAS,+BAA+B,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC3G,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,OAAgB;QAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAS,4BAA4B,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAChG,CAAC;QACD,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAS,0BAA0B,CAAC,CAAC,IAAI,EAAE,CAAC;IACnF,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,OAAe;QAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAS,+BAA+B,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAClG,CAAC;CACF;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,4CAA4C;AAC5C,MAAM,CAAC,MAAM,UAAU,GAA2C;IAChE,IAAI,EAAE,QAAQ;IACd,IAAI,CAAC,SAAoB,EAAE,QAAyB;QAClD,OAAO,EAAE,MAAM,EAAE,IAAI,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC;IAC9D,CAAC;CACF,CAAC"}

package/dist/sql/index.d.ts

@@ -0,0 +1,31 @@
+import type { NucleusPlugin, IsolationLevel } from '../types.js';
+export interface SQLModel {
+    /** Query rows into typed results. */
+    query<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T[]>;
+    /** Query exactly one row. Throws `NucleusNotFoundError` if none. */
+    queryOne<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T>;
+    /** Query one row, or `null` if none. */
+    queryOneOrNull<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T | null>;
+    /** Execute a DML statement and return the affected row count. */
+    execute(sql: string, ...params: unknown[]): Promise<number>;
+    /** Execute many statements in batch and return each affected-row count. */
+    executeBatch(statements: Array<{
+        sql: string;
+        params?: unknown[];
+    }>): Promise<number[]>;
+    /** Fetch a single scalar value from the first column of the first row. */
+    fetchval<T = unknown>(sql: string, ...params: unknown[]): Promise<T | null>;
+    /**
+     * Run `fn` inside a transaction. Commits on success, rolls back on error.
+     * The callback receives a scoped `SQLModel` whose operations all execute
+     * within the same transaction.
+     */
+    transaction<T>(fn: (tx: SQLModel) => Promise<T>, opts?: {
+        isolationLevel?: IsolationLevel;
+    }): Promise<T>;
+}
+/** Plugin: adds `.sql` to the client. */
+export declare const withSQL: NucleusPlugin<{
+    sql: SQLModel;
+}>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sql/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,aAAa,EAAmB,cAAc,EAAE,MAAM,aAAa,CAAC;AAO7F,MAAM,WAAW,QAAQ;IACvB,qCAAqC;IACrC,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEpF,oEAAoE;IACpE,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAErF,wCAAwC;IACxC,cAAc,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAElG,iEAAiE;IACjE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5D,2EAA2E;IAC3E,YAAY,CAAC,UAAU,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAExF,0EAA0E;IAC1E,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAE5E;;;;OAIG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC1G;AAgED,yCAAyC;AACzC,eAAO,MAAM,OAAO,EAAE,aAAa,CAAC;IAAE,GAAG,EAAE,QAAQ,CAAA;CAAE,CAKpD,CAAC"}

package/dist/sql/index.js

@@ -0,0 +1,65 @@
+// ---------------------------------------------------------------------------
+// @neutron/nucleus/sql — SQL model plugin
+// ---------------------------------------------------------------------------
+import { NucleusNotFoundError } from '../errors.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class SQLModelImpl {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async query(sql, ...params) {
+        const result = await this.transport.query(sql, params);
+        return result.rows;
+    }
+    async queryOne(sql, ...params) {
+        const rows = await this.query(sql, ...params);
+        if (rows.length === 0) {
+            throw new NucleusNotFoundError('Expected one row but found none');
+        }
+        return rows[0];
+    }
+    async queryOneOrNull(sql, ...params) {
+        const rows = await this.query(sql, ...params);
+        return rows.length > 0 ? rows[0] : null;
+    }
+    async execute(sql, ...params) {
+        return this.transport.execute(sql, params);
+    }
+    async executeBatch(statements) {
+        const results = [];
+        for (const stmt of statements) {
+            results.push(await this.transport.execute(stmt.sql, stmt.params));
+        }
+        return results;
+    }
+    async fetchval(sql, ...params) {
+        return this.transport.fetchval(sql, params);
+    }
+    async transaction(fn, opts) {
+        const txTransport = await this.transport.beginTransaction(opts?.isolationLevel);
+        const txSql = new SQLModelImpl(txTransport);
+        try {
+            const result = await fn(txSql);
+            await txTransport.commit();
+            return result;
+        }
+        catch (err) {
+            await txTransport.rollback();
+            throw err;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/** Plugin: adds `.sql` to the client. */
+export const withSQL = {
+    name: 'sql',
+    init(transport, _features) {
+        return { sql: new SQLModelImpl(transport) };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/sql/index.js.map

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

package/dist/streams/index.d.ts

@@ -0,0 +1,26 @@
+import type { NucleusPlugin } from '../types.js';
+export interface StreamEntry {
+    id: string;
+    fields: Record<string, unknown>;
+}
+export interface StreamsModel {
+    /** Append an entry to a stream. Returns the generated entry ID. */
+    xadd(stream: string, fields: Record<string, unknown>): Promise<string>;
+    /** Return the number of entries in a stream. */
+    xlen(stream: string): Promise<number>;
+    /** Return entries between `startMs` and `endMs` timestamps (inclusive). */
+    xrange(stream: string, startMs: number, endMs: number, count: number): Promise<StreamEntry[]>;
+    /** Read new entries after `lastIdMs`. */
+    xread(stream: string, lastIdMs: number, count: number): Promise<StreamEntry[]>;
+    /** Create a consumer group on a stream. */
+    xgroupCreate(stream: string, group: string, startId: number): Promise<boolean>;
+    /** Read entries from a consumer group. */
+    xreadGroup(stream: string, group: string, consumer: string, count: number): Promise<StreamEntry[]>;
+    /** Acknowledge processing of an entry in a consumer group. */
+    xack(stream: string, group: string, idMs: number, idSeq: number): Promise<boolean>;
+}
+/** Plugin: adds `.streams` to the client. */
+export declare const withStreams: NucleusPlugin<{
+    streams: StreamsModel;
+}>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/streams/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,aAAa,EAAmB,MAAM,aAAa,CAAC;AAO7E,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAMD,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEvE,gDAAgD;IAChD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEtC,2EAA2E;IAC3E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAE9F,yCAAyC;IACzC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAE/E,2CAA2C;IAC3C,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE/E,0CAA0C;IAC1C,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAEnG,8DAA8D;IAC9D,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpF;AAmFD,6CAA6C;AAC7C,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC;IAAE,OAAO,EAAE,YAAY,CAAA;CAAE,CAKhE,CAAC"}