@neutron-build/nucleus 0.1.0

package/dist/document/index.d.ts

@@ -0,0 +1,42 @@
+import type { NucleusPlugin } from '../types.js';
+export interface DocFindOptions {
+    /** Sort by this field. */
+    sortField?: string;
+    /** Sort ascending (`true`) or descending (`false`). */
+    sortAsc?: boolean;
+    /** Skip the first `n` results. */
+    skip?: number;
+    /** Maximum number of results. */
+    limit?: number;
+    /** Only return these fields from each document. */
+    fields?: string[];
+}
+export interface DocumentModel {
+    /** Insert a document. Returns the generated document ID. */
+    insert(collection: string, doc: Record<string, unknown>): Promise<number>;
+    /** Get a document by ID. Returns `null` if not found. */
+    get(id: number): Promise<Record<string, unknown> | null>;
+    /** Get a document and cast it to `T`. Returns `null` if not found. */
+    getTyped<T>(id: number): Promise<T | null>;
+    /** Query documents matching a JSON filter. Returns matching IDs. */
+    queryDocs(filter: Record<string, unknown>): Promise<number[]>;
+    /** Extract a nested value from a document by key path. */
+    path(id: number, ...keys: string[]): Promise<string | null>;
+    /** Return the total number of documents. */
+    count(): Promise<number>;
+    /** Find full documents matching a filter. */
+    find(collection: string, filter: Record<string, unknown>, opts?: DocFindOptions): Promise<Record<string, unknown>[]>;
+    /** Find and return typed results. */
+    findTyped<T>(collection: string, filter: Record<string, unknown>, opts?: DocFindOptions): Promise<T[]>;
+    /** Find the first document matching a filter. */
+    findOne(collection: string, filter: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    /** Update documents matching a filter with the given partial. Returns count of updated docs. */
+    update(collection: string, filter: Record<string, unknown>, update: Record<string, unknown>): Promise<number>;
+    /** Delete documents matching a filter. Returns count of deleted docs. */
+    delete(collection: string, filter: Record<string, unknown>): Promise<number>;
+}
+/** Plugin: adds `.document` to the client. */
+export declare const withDocument: NucleusPlugin<{
+    document: DocumentModel;
+}>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/document/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,aAAa,EAAmB,MAAM,aAAa,CAAC;AAO7E,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1E,yDAAyD;IACzD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAEzD,sEAAsE;IACtE,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAE3C,oEAAoE;IACpE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE9D,0DAA0D;IAC1D,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE5D,4CAA4C;IAC5C,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzB,6CAA6C;IAC7C,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IAErH,qCAAqC;IACrC,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEvG,iDAAiD;IACjD,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAEtG,gGAAgG;IAChG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9G,yEAAyE;IACzE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9E;AAgLD,8CAA8C;AAC9C,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC;IAAE,QAAQ,EAAE,aAAa,CAAA;CAAE,CAKnE,CAAC"}

package/dist/document/index.js

@@ -0,0 +1,154 @@
+// ---------------------------------------------------------------------------
+// @neutron/nucleus/document — Document / JSON model plugin
+// ---------------------------------------------------------------------------
+import { requireNucleus } from '../helpers.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class DocumentModelImpl {
+    transport;
+    features;
+    constructor(transport, features) {
+        this.transport = transport;
+        this.features = features;
+    }
+    require() {
+        requireNucleus(this.features, 'Document');
+    }
+    async insert(_collection, doc) {
+        this.require();
+        const data = JSON.stringify(doc);
+        return (await this.transport.fetchval('SELECT DOC_INSERT($1)', [data])) ?? 0;
+    }
+    async get(id) {
+        this.require();
+        const raw = await this.transport.fetchval('SELECT DOC_GET($1)', [id]);
+        if (raw === null)
+            return null;
+        return JSON.parse(raw);
+    }
+    async getTyped(id) {
+        this.require();
+        const raw = await this.transport.fetchval('SELECT DOC_GET($1)', [id]);
+        if (raw === null)
+            return null;
+        return JSON.parse(raw);
+    }
+    async queryDocs(filter) {
+        this.require();
+        const q = JSON.stringify(filter);
+        const raw = await this.transport.fetchval('SELECT DOC_QUERY($1)', [q]);
+        if (!raw)
+            return [];
+        return raw
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean)
+            .map(Number)
+            .filter((n) => !Number.isNaN(n));
+    }
+    async path(id, ...keys) {
+        this.require();
+        const placeholders = keys.map((_, i) => `$${i + 2}`).join(', ');
+        const sql = `SELECT DOC_PATH($1, ${placeholders})`;
+        return this.transport.fetchval(sql, [id, ...keys]);
+    }
+    async count() {
+        this.require();
+        return (await this.transport.fetchval('SELECT DOC_COUNT()')) ?? 0;
+    }
+    async find(collection, filter, opts = {}) {
+        const ids = await this.queryDocs(filter);
+        let results = [];
+        for (const id of ids) {
+            const doc = await this.get(id);
+            if (doc)
+                results.push(doc);
+        }
+        // Sort
+        if (opts.sortField) {
+            const field = opts.sortField;
+            const asc = opts.sortAsc ?? true;
+            results.sort((a, b) => {
+                const va = String(a[field] ?? '');
+                const vb = String(b[field] ?? '');
+                return asc ? va.localeCompare(vb) : vb.localeCompare(va);
+            });
+        }
+        // Skip
+        if (opts.skip && opts.skip > 0) {
+            results = results.slice(opts.skip);
+        }
+        // Limit
+        if (opts.limit && opts.limit > 0) {
+            results = results.slice(0, opts.limit);
+        }
+        // Projection
+        if (opts.fields && opts.fields.length > 0) {
+            const keep = new Set(opts.fields);
+            results = results.map((doc) => {
+                const projected = {};
+                for (const f of keep) {
+                    if (f in doc)
+                        projected[f] = doc[f];
+                }
+                return projected;
+            });
+        }
+        return results;
+    }
+    async findTyped(collection, filter, opts = {}) {
+        const ids = await this.queryDocs(filter);
+        let results = [];
+        for (const id of ids) {
+            const item = await this.getTyped(id);
+            if (item !== null)
+                results.push(item);
+        }
+        if (opts.skip && opts.skip > 0)
+            results = results.slice(opts.skip);
+        if (opts.limit && opts.limit > 0)
+            results = results.slice(0, opts.limit);
+        return results;
+    }
+    async findOne(collection, filter) {
+        const docs = await this.find(collection, filter, { limit: 1 });
+        return docs.length > 0 ? docs[0] : null;
+    }
+    async update(collection, filter, update) {
+        this.require();
+        const ids = await this.queryDocs(filter);
+        let count = 0;
+        for (const id of ids) {
+            const doc = await this.get(id);
+            if (!doc)
+                continue;
+            Object.assign(doc, update);
+            const data = JSON.stringify(doc);
+            await this.transport.execute('UPDATE documents SET data = $1::jsonb WHERE id = $2', [data, id]);
+            count++;
+        }
+        return count;
+    }
+    async delete(collection, filter) {
+        this.require();
+        const ids = await this.queryDocs(filter);
+        let count = 0;
+        for (const id of ids) {
+            await this.transport.execute('DELETE FROM documents WHERE id = $1', [id]);
+            count++;
+        }
+        return count;
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/** Plugin: adds `.document` to the client. */
+export const withDocument = {
+    name: 'document',
+    init(transport, features) {
+        return { document: new DocumentModelImpl(transport, features) };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/document/index.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+export interface NucleusErrorOptions {
+    cause?: Error;
+    meta?: Record<string, unknown>;
+}
+/** Base error for all Nucleus operations. */
+export declare class NucleusError extends Error {
+    readonly code: string;
+    readonly meta?: Record<string, unknown>;
+    constructor(code: string, message: string, options?: NucleusErrorOptions);
+}
+/** Thrown when a connection cannot be established or is lost. */
+export declare class NucleusConnectionError extends NucleusError {
+    constructor(message: string, options?: NucleusErrorOptions);
+}
+/** Thrown when a SQL query or command fails on the server. */
+export declare class NucleusQueryError extends NucleusError {
+    constructor(message: string, options?: NucleusErrorOptions);
+}
+/** Thrown when an expected row or resource is not found. */
+export declare class NucleusNotFoundError extends NucleusError {
+    constructor(message: string, options?: NucleusErrorOptions);
+}
+/** Thrown on unique-constraint violations or optimistic-lock conflicts. */
+export declare class NucleusConflictError extends NucleusError {
+    constructor(message: string, options?: NucleusErrorOptions);
+}
+/** Thrown when a transaction fails to commit or is aborted. */
+export declare class NucleusTransactionError extends NucleusError {
+    constructor(message: string, options?: NucleusErrorOptions);
+}
+/** Thrown when a Nucleus-only feature is used against plain PostgreSQL. */
+export declare class NucleusFeatureError extends NucleusError {
+    constructor(feature: string, options?: NucleusErrorOptions);
+}
+/** Thrown when the server rejects the request for authentication reasons. */
+export declare class NucleusAuthError extends NucleusError {
+    constructor(message: string, options?: NucleusErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,6CAA6C;AAC7C,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAE5B,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB;CAMzE;AAED,iEAAiE;AACjE,qBAAa,sBAAuB,SAAQ,YAAY;gBAC1C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB;CAI3D;AAED,8DAA8D;AAC9D,qBAAa,iBAAkB,SAAQ,YAAY;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB;CAI3D;AAED,4DAA4D;AAC5D,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB;CAI3D;AAED,2EAA2E;AAC3E,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB;CAI3D;AAED,+DAA+D;AAC/D,qBAAa,uBAAwB,SAAQ,YAAY;gBAC3C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB;CAI3D;AAED,2EAA2E;AAC3E,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB;CAQ3D;AAED,6EAA6E;AAC7E,qBAAa,gBAAiB,SAAQ,YAAY;gBACpC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB;CAI3D"}

package/dist/errors.js

@@ -0,0 +1,64 @@
+// ---------------------------------------------------------------------------
+// Nucleus client — error hierarchy
+// ---------------------------------------------------------------------------
+/** Base error for all Nucleus operations. */
+export class NucleusError extends Error {
+    code;
+    meta;
+    constructor(code, message, options) {
+        super(message, { cause: options?.cause });
+        this.name = 'NucleusError';
+        this.code = code;
+        this.meta = options?.meta;
+    }
+}
+/** Thrown when a connection cannot be established or is lost. */
+export class NucleusConnectionError extends NucleusError {
+    constructor(message, options) {
+        super('CONNECTION_ERROR', message, options);
+        this.name = 'NucleusConnectionError';
+    }
+}
+/** Thrown when a SQL query or command fails on the server. */
+export class NucleusQueryError extends NucleusError {
+    constructor(message, options) {
+        super('QUERY_ERROR', message, options);
+        this.name = 'NucleusQueryError';
+    }
+}
+/** Thrown when an expected row or resource is not found. */
+export class NucleusNotFoundError extends NucleusError {
+    constructor(message, options) {
+        super('NOT_FOUND', message, options);
+        this.name = 'NucleusNotFoundError';
+    }
+}
+/** Thrown on unique-constraint violations or optimistic-lock conflicts. */
+export class NucleusConflictError extends NucleusError {
+    constructor(message, options) {
+        super('CONFLICT', message, options);
+        this.name = 'NucleusConflictError';
+    }
+}
+/** Thrown when a transaction fails to commit or is aborted. */
+export class NucleusTransactionError extends NucleusError {
+    constructor(message, options) {
+        super('TRANSACTION_ERROR', message, options);
+        this.name = 'NucleusTransactionError';
+    }
+}
+/** Thrown when a Nucleus-only feature is used against plain PostgreSQL. */
+export class NucleusFeatureError extends NucleusError {
+    constructor(feature, options) {
+        super('FEATURE_UNAVAILABLE', `${feature} requires Nucleus database, but connected to plain PostgreSQL`, options);
+        this.name = 'NucleusFeatureError';
+    }
+}
+/** Thrown when the server rejects the request for authentication reasons. */
+export class NucleusAuthError extends NucleusError {
+    constructor(message, options) {
+        super('AUTH_ERROR', message, options);
+        this.name = 'NucleusAuthError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mCAAmC;AACnC,8EAA8E;AAO9E,6CAA6C;AAC7C,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAS;IACb,IAAI,CAA2B;IAExC,YAAY,IAAY,EAAE,OAAe,EAAE,OAA6B;QACtE,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,CAAC;IAC5B,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,OAAO,sBAAuB,SAAQ,YAAY;IACtD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,kBAAkB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,8DAA8D;AAC9D,MAAM,OAAO,iBAAkB,SAAQ,YAAY;IACjD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,aAAa,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,4DAA4D;AAC5D,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,OAAO,uBAAwB,SAAQ,YAAY;IACvD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,mBAAmB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IACnD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CACH,qBAAqB,EACrB,GAAG,OAAO,+DAA+D,EACzE,OAAO,CACR,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAChD,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/features.d.ts

@@ -0,0 +1,14 @@
+import type { Transport, NucleusFeatures } from './types.js';
+/**
+ * Detect capabilities of the connected database.
+ *
+ * Detection strategy:
+ * 1. `SELECT VERSION()` — if it contains "Nucleus", we know this is Nucleus.
+ * 2. If Nucleus is detected, query `nucleus_features()` for granular per-model
+ *    availability. This allows partial installations where some engines are
+ *    disabled or not yet loaded.
+ * 3. On plain PostgreSQL the result is a standard PG version string and only
+ *    SQL features are enabled.
+ */
+export declare function detectFeatures(transport: Transport): Promise<NucleusFeatures>;
+//# sourceMappingURL=features.d.ts.map

package/dist/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC,CAwEnF"}

package/dist/features.js

@@ -0,0 +1,85 @@
+// ---------------------------------------------------------------------------
+// Nucleus client — feature detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect capabilities of the connected database.
+ *
+ * Detection strategy:
+ * 1. `SELECT VERSION()` — if it contains "Nucleus", we know this is Nucleus.
+ * 2. If Nucleus is detected, query `nucleus_features()` for granular per-model
+ *    availability. This allows partial installations where some engines are
+ *    disabled or not yet loaded.
+ * 3. On plain PostgreSQL the result is a standard PG version string and only
+ *    SQL features are enabled.
+ */
+export async function detectFeatures(transport) {
+    const version = await transport.fetchval('SELECT VERSION()');
+    const ver = version ?? '';
+    const isNucleus = ver.includes('Nucleus');
+    if (!isNucleus) {
+        return {
+            isNucleus: false,
+            hasKV: false,
+            hasVector: false,
+            hasTimeSeries: false,
+            hasDocument: false,
+            hasGraph: false,
+            hasFTS: false,
+            hasGeo: false,
+            hasBlob: false,
+            hasStreams: false,
+            hasColumnar: false,
+            hasDatalog: false,
+            hasCDC: false,
+            hasPubSub: false,
+            version: ver,
+        };
+    }
+    // Attempt granular feature detection via nucleus_features() function.
+    // If the function does not exist (older Nucleus builds), fall back to all=true.
+    try {
+        const raw = await transport.fetchval('SELECT NUCLEUS_FEATURES()');
+        if (raw) {
+            const features = JSON.parse(raw);
+            return {
+                isNucleus: true,
+                hasKV: features.kv !== false,
+                hasVector: features.vector !== false,
+                hasTimeSeries: features.timeseries !== false,
+                hasDocument: features.document !== false,
+                hasGraph: features.graph !== false,
+                hasFTS: features.fts !== false,
+                hasGeo: features.geo !== false,
+                hasBlob: features.blob !== false,
+                hasStreams: features.streams !== false,
+                hasColumnar: features.columnar !== false,
+                hasDatalog: features.datalog !== false,
+                hasCDC: features.cdc !== false,
+                hasPubSub: features.pubsub !== false,
+                version: ver,
+            };
+        }
+    }
+    catch {
+        // NUCLEUS_FEATURES() not available — fall through to all-enabled default.
+    }
+    // All models enabled by default on Nucleus.
+    return {
+        isNucleus: true,
+        hasKV: true,
+        hasVector: true,
+        hasTimeSeries: true,
+        hasDocument: true,
+        hasGraph: true,
+        hasFTS: true,
+        hasGeo: true,
+        hasBlob: true,
+        hasStreams: true,
+        hasColumnar: true,
+        hasDatalog: true,
+        hasCDC: true,
+        hasPubSub: true,
+        version: ver,
+    };
+}
+//# sourceMappingURL=features.js.map

package/dist/features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.js","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,qCAAqC;AACrC,8EAA8E;AAI9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,SAAoB;IACvD,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAS,kBAAkB,CAAC,CAAC;IACrE,MAAM,GAAG,GAAG,OAAO,IAAI,EAAE,CAAC;IAE1B,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAE1C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO;YACL,SAAS,EAAE,KAAK;YAChB,KAAK,EAAE,KAAK;YACZ,SAAS,EAAE,KAAK;YAChB,aAAa,EAAE,KAAK;YACpB,WAAW,EAAE,KAAK;YAClB,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,KAAK;YACd,UAAU,EAAE,KAAK;YACjB,WAAW,EAAE,KAAK;YAClB,UAAU,EAAE,KAAK;YACjB,MAAM,EAAE,KAAK;YACb,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,GAAG;SACb,CAAC;IACJ,CAAC;IAED,sEAAsE;IACtE,gFAAgF;IAChF,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAS,2BAA2B,CAAC,CAAC;QAC1E,IAAI,GAAG,EAAE,CAAC;YACR,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;YAC5D,OAAO;gBACL,SAAS,EAAE,IAAI;gBACf,KAAK,EAAE,QAAQ,CAAC,EAAE,KAAK,KAAK;gBAC5B,SAAS,EAAE,QAAQ,CAAC,MAAM,KAAK,KAAK;gBACpC,aAAa,EAAE,QAAQ,CAAC,UAAU,KAAK,KAAK;gBAC5C,WAAW,EAAE,QAAQ,CAAC,QAAQ,KAAK,KAAK;gBACxC,QAAQ,EAAE,QAAQ,CAAC,KAAK,KAAK,KAAK;gBAClC,MAAM,EAAE,QAAQ,CAAC,GAAG,KAAK,KAAK;gBAC9B,MAAM,EAAE,QAAQ,CAAC,GAAG,KAAK,KAAK;gBAC9B,OAAO,EAAE,QAAQ,CAAC,IAAI,KAAK,KAAK;gBAChC,UAAU,EAAE,QAAQ,CAAC,OAAO,KAAK,KAAK;gBACtC,WAAW,EAAE,QAAQ,CAAC,QAAQ,KAAK,KAAK;gBACxC,UAAU,EAAE,QAAQ,CAAC,OAAO,KAAK,KAAK;gBACtC,MAAM,EAAE,QAAQ,CAAC,GAAG,KAAK,KAAK;gBAC9B,SAAS,EAAE,QAAQ,CAAC,MAAM,KAAK,KAAK;gBACpC,OAAO,EAAE,GAAG;aACb,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;IAC5E,CAAC;IAED,4CAA4C;IAC5C,OAAO;QACL,SAAS,EAAE,IAAI;QACf,KAAK,EAAE,IAAI;QACX,SAAS,EAAE,IAAI;QACf,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,IAAI;QACjB,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,IAAI;QACZ,MAAM,EAAE,IAAI;QACZ,OAAO,EAAE,IAAI;QACb,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,IAAI;QAChB,MAAM,EAAE,IAAI;QACZ,SAAS,EAAE,IAAI;QACf,OAAO,EAAE,GAAG;KACb,CAAC;AACJ,CAAC"}

package/dist/fts/index.d.ts

@@ -0,0 +1,35 @@
+import type { NucleusPlugin } from '../types.js';
+export interface FTSResult {
+    docId: number;
+    score: number;
+    highlight?: Record<string, string>;
+}
+export interface FTSSearchOptions {
+    /** Enable fuzzy matching with the given edit distance. */
+    fuzzyDistance?: number;
+    /** Maximum number of results (default 10). */
+    limit?: number;
+    /** Fields to highlight in results. */
+    highlight?: string[];
+    /** Fields to compute facet counts for. */
+    facets?: string[];
+}
+export interface FTSModel {
+    /** Add a document's text to the full-text index. */
+    index(docId: number, text: string): Promise<boolean>;
+    /** Search the full-text index. */
+    search(query: string, opts?: FTSSearchOptions): Promise<FTSResult[]>;
+    /** Remove a document from the index. */
+    remove(docId: number): Promise<boolean>;
+    /** Return the number of indexed documents. */
+    docCount(): Promise<number>;
+    /** Return the number of indexed terms. */
+    termCount(): Promise<number>;
+    /** Create a named FTS index with the given configuration. */
+    createIndex(name: string, config: Record<string, unknown>): Promise<void>;
+}
+/** Plugin: adds `.fts` to the client. */
+export declare const withFTS: NucleusPlugin<{
+    fts: FTSModel;
+}>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fts/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,aAAa,EAAmB,MAAM,aAAa,CAAC;AAO7E,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD,MAAM,WAAW,QAAQ;IACvB,oDAAoD;IACpD,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAErD,kCAAkC;IAClC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAErE,wCAAwC;IACxC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAExC,8CAA8C;IAC9C,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5B,0CAA0C;IAC1C,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE7B,6DAA6D;IAC7D,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3E;AA2ED,yCAAyC;AACzC,eAAO,MAAM,OAAO,EAAE,aAAa,CAAC;IAAE,GAAG,EAAE,QAAQ,CAAA;CAAE,CAKpD,CAAC"}

package/dist/fts/index.js

@@ -0,0 +1,76 @@
+// ---------------------------------------------------------------------------
+// @neutron/nucleus/fts — Full-Text Search model plugin
+// ---------------------------------------------------------------------------
+import { requireNucleus } from '../helpers.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class FTSModelImpl {
+    transport;
+    features;
+    constructor(transport, features) {
+        this.transport = transport;
+        this.features = features;
+    }
+    require() {
+        requireNucleus(this.features, 'FTS');
+    }
+    async index(docId, text) {
+        this.require();
+        return (await this.transport.fetchval('SELECT FTS_INDEX($1, $2)', [docId, text])) ?? false;
+    }
+    async search(query, opts = {}) {
+        this.require();
+        const limit = opts.limit ?? 10;
+        let raw;
+        if (opts.fuzzyDistance && opts.fuzzyDistance > 0) {
+            raw = await this.transport.fetchval('SELECT FTS_FUZZY_SEARCH($1, $2, $3)', [
+                query,
+                opts.fuzzyDistance,
+                limit,
+            ]);
+        }
+        else {
+            raw = await this.transport.fetchval('SELECT FTS_SEARCH($1, $2)', [query, limit]);
+        }
+        if (!raw)
+            return [];
+        const results = JSON.parse(raw);
+        // Ensure highlight map is present when requested
+        if (opts.highlight && opts.highlight.length > 0) {
+            for (const r of results) {
+                if (!r.highlight)
+                    r.highlight = {};
+            }
+        }
+        return results;
+    }
+    async remove(docId) {
+        this.require();
+        return (await this.transport.fetchval('SELECT FTS_REMOVE($1)', [docId])) ?? false;
+    }
+    async docCount() {
+        this.require();
+        return (await this.transport.fetchval('SELECT FTS_DOC_COUNT()')) ?? 0;
+    }
+    async termCount() {
+        this.require();
+        return (await this.transport.fetchval('SELECT FTS_TERM_COUNT()')) ?? 0;
+    }
+    async createIndex(name, config) {
+        this.require();
+        const configJson = JSON.stringify(config);
+        await this.transport.execute('SELECT FTS_INDEX($1, $2)', [name, configJson]);
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/** Plugin: adds `.fts` to the client. */
+export const withFTS = {
+    name: 'fts',
+    init(transport, features) {
+        return { fts: new FTSModelImpl(transport, features) };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/fts/index.js.map

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

package/dist/geo/index.d.ts

@@ -0,0 +1,34 @@
+import type { NucleusPlugin } from '../types.js';
+export interface GeoPoint {
+    lat: number;
+    lon: number;
+}
+export interface GeoFeature {
+    id: string;
+    lat: number;
+    lon: number;
+    properties: Record<string, unknown>;
+}
+export interface GeoModel {
+    /** Haversine distance in metres between two points. */
+    distance(a: GeoPoint, b: GeoPoint): Promise<number>;
+    /** Euclidean distance between two points. */
+    distanceEuclidean(a: GeoPoint, b: GeoPoint): Promise<number>;
+    /** Check if `b` is within `radiusMeters` of `a`. */
+    within(a: GeoPoint, b: GeoPoint, radiusMeters: number): Promise<boolean>;
+    /** Calculate the area of a polygon (minimum 3 points). */
+    area(points: GeoPoint[]): Promise<number>;
+    /** Find features within a radius of a point. */
+    nearestTo(layer: string, point: GeoPoint, radiusMeters: number, limit: number): Promise<GeoFeature[]>;
+    /** Find features inside a bounding box. */
+    withinBBox(layer: string, minLat: number, minLon: number, maxLat: number, maxLon: number): Promise<GeoFeature[]>;
+    /** Find features inside a polygon. Each coordinate is `[lat, lon]`. */
+    withinPolygon(layer: string, polygon: [number, number][]): Promise<GeoFeature[]>;
+    /** Insert a geographic feature into a layer table. */
+    insert(layer: string, lat: number, lon: number, props: Record<string, unknown>): Promise<void>;
+}
+/** Plugin: adds `.geo` to the client. */
+export declare const withGeo: NucleusPlugin<{
+    geo: GeoModel;
+}>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/geo/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,aAAa,EAAmB,MAAM,aAAa,CAAC;AAO7E,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAMD,MAAM,WAAW,QAAQ;IACvB,uDAAuD;IACvD,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpD,6CAA6C;IAC7C,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE7D,oDAAoD;IACpD,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzE,0DAA0D;IAC1D,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1C,gDAAgD;IAChD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAEtG,2CAA2C;IAC3C,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAEjH,uEAAuE;IACvE,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAEjF,sDAAsD;IACtD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChG;AAkKD,yCAAyC;AACzC,eAAO,MAAM,OAAO,EAAE,aAAa,CAAC;IAAE,GAAG,EAAE,QAAQ,CAAA;CAAE,CAKpD,CAAC"}