omniql 0.5.2

package/README.md

@@ -0,0 +1,18 @@
+# OmniQL for TypeScript / Node.js
+
+A standardized, multi-database query language (OQL) for TypeScript/Node.js.
+
+## Installation
+
+```bash
+npm install omniql
+```
+
+## Usage
+
+```typescript
+import { OmniEngine } from 'omniql';
+
+const engine = new OmniEngine();
+// ...
+```

package/dist/omniql.d.ts

@@ -0,0 +1,121 @@
+/**
+ * OmniQL TypeScript / Node.js Binding
+ * =====================================
+ *
+ * A Node.js addon using N-API that wraps the OmniQL shared library and exposes
+ * a fully type-safe, Promise-based API with generated TypeScript definitions.
+ *
+ * Build the native library first:
+ *   go build -buildmode=c-shared -o libomniql.so ../../pkg/ffi
+ *
+ * Install:
+ *   npm install
+ *
+ * Example usage:
+ *   import { OmniEngine, Query } from 'omniql';
+ *
+ *   const engine = new OmniEngine();
+ *
+ *   // 1. Register a driver and route a target to it.
+ *   const driverName = engine.registerSQLiteDriver(':memory:');
+ *   engine.route('analytics_data', driverName);
+ *
+ *   // 2. Execute a query.
+ *   const result = await engine.execute({
+ *     target: 'analytics_data',
+ *     action: 'FIND',
+ *     filter: {
+ *       category: { $in: ['electronics', 'books'] },
+ *       price:    { $lt: 500 },
+ *     },
+ *     options: { limit: 20 },
+ *   });
+ *
+ *   console.log(result.data);
+ *   engine.close();
+ */
+export type Action = 'FIND' | 'INSERT' | 'UPDATE' | 'DELETE' | 'COUNT';
+export interface Filter {
+    [field: string]: unknown;
+}
+export interface QueryOptions {
+    limit?: number;
+    skip?: number;
+    sort?: Record<string, 1 | -1>;
+    fields?: Record<string, unknown>;
+}
+export interface Query {
+    target: string;
+    action?: Action;
+    filter?: Filter;
+    document?: Record<string, unknown>;
+    options?: QueryOptions;
+}
+export interface OmniMeta {
+    total: number;
+    returned: number;
+    driver: string;
+    target: string;
+}
+export interface OmniError {
+    code: string;
+    message: string;
+}
+export interface OmniResult<T = Record<string, unknown>> {
+    data: T[];
+    meta: OmniMeta;
+    error?: OmniError;
+}
+export interface CollectionSchema {
+    name: string;
+    fields: Record<string, {
+        type: string;
+        required?: boolean;
+    }>;
+}
+/**
+ * OmniEngine is the main entry-point for the OmniQL TypeScript binding.
+ *
+ * All `execute` calls are async and safe to use with `await`.
+ */
+export declare class OmniEngine {
+    private readonly handle;
+    constructor();
+    /**
+     * Executes an OQL query and returns the OmniJSON result.
+     */
+    execute<T = Record<string, unknown>>(query: Query): Promise<OmniResult<T>>;
+    /**
+     * Registers a collection schema with the engine.
+     */
+    registerSchema(schema: CollectionSchema): void;
+    /**
+     * Binds a collection/table target name to a driver name.
+     * Must be called after registering a driver.
+     *
+     * @param target     The collection or table name.
+     * @param driverName The driver name returned by a registerXxxDriver call.
+     */
+    route(target: string, driverName: string): void;
+    /**
+     * Registers a SQLite driver using the given DSN (file path or ":memory:").
+     * Returns the driver name ("sqlite") to use with {@link route}.
+     */
+    registerSQLiteDriver(dsn: string): string;
+    /**
+     * Registers a PostgreSQL driver using the given connection string.
+     * e.g. "host=localhost user=pg password=pg dbname=mydb sslmode=disable"
+     * Returns the driver name ("postgres") to use with {@link route}.
+     */
+    registerPostgresDriver(connStr: string): string;
+    /**
+     * Registers a MongoDB driver using the given URI and database name.
+     * e.g. uri = "mongodb://localhost:27017", dbName = "mydb"
+     * Returns the driver name ("mongo") to use with {@link route}.
+     */
+    registerMongoDriver(uri: string, dbName: string): string;
+    /**
+     * Releases the native engine handle.  Call when done.
+     */
+    close(): void;
+}

package/dist/omniql.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * OmniQL TypeScript / Node.js Binding
+ * =====================================
+ *
+ * A Node.js addon using N-API that wraps the OmniQL shared library and exposes
+ * a fully type-safe, Promise-based API with generated TypeScript definitions.
+ *
+ * Build the native library first:
+ *   go build -buildmode=c-shared -o libomniql.so ../../pkg/ffi
+ *
+ * Install:
+ *   npm install
+ *
+ * Example usage:
+ *   import { OmniEngine, Query } from 'omniql';
+ *
+ *   const engine = new OmniEngine();
+ *
+ *   // 1. Register a driver and route a target to it.
+ *   const driverName = engine.registerSQLiteDriver(':memory:');
+ *   engine.route('analytics_data', driverName);
+ *
+ *   // 2. Execute a query.
+ *   const result = await engine.execute({
+ *     target: 'analytics_data',
+ *     action: 'FIND',
+ *     filter: {
+ *       category: { $in: ['electronics', 'books'] },
+ *       price:    { $lt: 500 },
+ *     },
+ *     options: { limit: 20 },
+ *   });
+ *
+ *   console.log(result.data);
+ *   engine.close();
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OmniEngine = void 0;
+const ffi = __importStar(require("ffi-napi"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+// ---------------------------------------------------------------------------
+// Native library loader
+// ---------------------------------------------------------------------------
+const LIB_SEARCH_PATHS = [
+    path.join(__dirname, 'libomniql.so'),
+    path.join(__dirname, 'libomniql.dylib'),
+    path.join(__dirname, 'omniql.dll'),
+    'libomniql',
+];
+function loadLib() {
+    for (const p of LIB_SEARCH_PATHS) {
+        if (fs.existsSync(p)) {
+            return ffi.Library(p, {
+                OmniQL_NewEngine: ['int', []],
+                OmniQL_FreeEngine: ['void', ['int']],
+                OmniQL_Execute: ['string', ['int', 'string']],
+                OmniQL_RegisterSchema: ['string', ['int', 'string']],
+                OmniQL_Route: ['string', ['int', 'string', 'string']],
+                OmniQL_RegisterSQLiteDriver: ['string', ['int', 'string']],
+                OmniQL_RegisterPostgresDriver: ['string', ['int', 'string']],
+                OmniQL_RegisterMongoDriver: ['string', ['int', 'string', 'string']],
+                OmniQL_Free: ['void', ['pointer']],
+            });
+        }
+    }
+    throw new Error('OmniQL native library not found. ' +
+        'Build it with: go build -buildmode=c-shared -o libomniql.so ../../pkg/ffi');
+}
+const lib = loadLib();
+// ---------------------------------------------------------------------------
+// OmniEngine class
+// ---------------------------------------------------------------------------
+/**
+ * OmniEngine is the main entry-point for the OmniQL TypeScript binding.
+ *
+ * All `execute` calls are async and safe to use with `await`.
+ */
+class OmniEngine {
+    handle;
+    constructor() {
+        this.handle = lib.OmniQL_NewEngine();
+    }
+    /**
+     * Executes an OQL query and returns the OmniJSON result.
+     */
+    async execute(query) {
+        const queryWithDefaults = { action: 'FIND', ...query };
+        const json = JSON.stringify(queryWithDefaults);
+        return new Promise((resolve, reject) => {
+            try {
+                const raw = lib.OmniQL_Execute(this.handle, json);
+                resolve(JSON.parse(raw));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    }
+    /**
+     * Registers a collection schema with the engine.
+     */
+    registerSchema(schema) {
+        lib.OmniQL_RegisterSchema(this.handle, JSON.stringify(schema));
+    }
+    /**
+     * Binds a collection/table target name to a driver name.
+     * Must be called after registering a driver.
+     *
+     * @param target     The collection or table name.
+     * @param driverName The driver name returned by a registerXxxDriver call.
+     */
+    route(target, driverName) {
+        lib.OmniQL_Route(this.handle, target, driverName);
+    }
+    /**
+     * Registers a SQLite driver using the given DSN (file path or ":memory:").
+     * Returns the driver name ("sqlite") to use with {@link route}.
+     */
+    registerSQLiteDriver(dsn) {
+        const raw = lib.OmniQL_RegisterSQLiteDriver(this.handle, dsn);
+        return JSON.parse(raw).driver ?? 'sqlite';
+    }
+    /**
+     * Registers a PostgreSQL driver using the given connection string.
+     * e.g. "host=localhost user=pg password=pg dbname=mydb sslmode=disable"
+     * Returns the driver name ("postgres") to use with {@link route}.
+     */
+    registerPostgresDriver(connStr) {
+        const raw = lib.OmniQL_RegisterPostgresDriver(this.handle, connStr);
+        return JSON.parse(raw).driver ?? 'postgres';
+    }
+    /**
+     * Registers a MongoDB driver using the given URI and database name.
+     * e.g. uri = "mongodb://localhost:27017", dbName = "mydb"
+     * Returns the driver name ("mongo") to use with {@link route}.
+     */
+    registerMongoDriver(uri, dbName) {
+        const raw = lib.OmniQL_RegisterMongoDriver(this.handle, uri, dbName);
+        return JSON.parse(raw).driver ?? 'mongo';
+    }
+    /**
+     * Releases the native engine handle.  Call when done.
+     */
+    close() {
+        lib.OmniQL_FreeEngine(this.handle);
+    }
+}
+exports.OmniEngine = OmniEngine;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "omniql",
+  "version": "0.5.2",
+  "description": "A standardized, multi-database query language (OQL) for TypeScript/Node.js.",
+  "main": "dist/omniql.js",
+  "types": "dist/omniql.d.ts",
+  "files": [
+    "dist",
+    "*.so",
+    "*.dll",
+    "*.dylib"
+  ],
+  "author": "Uttam Mahata <uttam-mahata-cs@outlook.com>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "ffi-napi": "^4.0.3",
+    "ref-napi": "^3.0.3"
+  },
+  "devDependencies": {
+    "@types/ffi-napi": "^4.0.10",
+    "@types/node": "^20.0.0",
+    "@types/ref-napi": "^3.0.12",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}