@ladybugdb/core-linux-arm64 0.15.2

package/database.js

@@ -0,0 +1,211 @@
+"use strict";
+
+const LbugNative = require("./lbug_native.js");
+
+class Database {
+  /**
+   * Initialize a new Database object. Note that the initialization is done
+   * lazily, so the database file is not opened until the first query is
+   * executed. To initialize the database immediately, call the `init()`
+   * function on the returned object.
+   *
+   * @param {String} databasePath path to the database file. If the path is not specified, or empty, or equal to
+   `:memory:`, the database will be created in memory.
+   * @param {Number} bufferManagerSize size of the buffer manager in bytes.
+   * @param {Boolean} enableCompression whether to enable compression.
+   * @param {Boolean} readOnly if true, database will be opened in read-only mode.
+   * @param {Number} maxDBSize maximum size of the database file in bytes. Note that
+   * this is introduced temporarily for now to get around with the default 8TB mmap
+   * address space limit some environment.
+   * @param {Boolean} autoCheckpoint If true, the database will automatically checkpoint when the size of
+   * the WAL file exceeds the checkpoint threshold.
+   * @param {Number} checkpointThreshold The threshold of the WAL file size in bytes. When the size of the
+   * WAL file exceeds this threshold, the database will checkpoint if autoCheckpoint is true.
+   * @param {Boolean} throwOnWalReplayFailure If true, any WAL replaying failure when loading the database
+   * will throw an error. Otherwise, Lbug will silently ignore the failure and replay up to where
+   * the error occured.
+   * @param {Boolean} enableChecksums If true, the database will use checksums to detect corruption in the
+   * WAL file.
+   */
+  constructor(
+    databasePath,
+    bufferManagerSize = 0,
+    enableCompression = true,
+    readOnly = false,
+    maxDBSize = 0,
+    autoCheckpoint = true,
+    checkpointThreshold = -1,
+    throwOnWalReplayFailure = true,
+    enableChecksums = true,
+  ) {
+    if (!databasePath) {
+      databasePath = ":memory:";
+    }
+    else if (typeof databasePath !== "string") {
+      throw new Error("Database path must be a string.");
+    }
+    if (typeof bufferManagerSize !== "number" || bufferManagerSize < 0) {
+      throw new Error("Buffer manager size must be a positive integer.");
+    }
+    if (typeof maxDBSize !== "number" || maxDBSize < 0) {
+      throw new Error("Max DB size must be a positive integer.");
+    }
+    if (typeof checkpointThreshold !== "number" || maxDBSize < -1) {
+      throw new Error("Checkpoint threshold must be a positive integer.");
+    }
+    bufferManagerSize = Math.floor(bufferManagerSize);
+    maxDBSize = Math.floor(maxDBSize);
+    checkpointThreshold = Math.floor(checkpointThreshold);
+    this._database = new LbugNative.NodeDatabase(
+      databasePath,
+      bufferManagerSize,
+      enableCompression,
+      readOnly,
+      maxDBSize,
+      autoCheckpoint,
+      checkpointThreshold,
+      throwOnWalReplayFailure,
+      enableChecksums
+    );
+    this._isInitialized = false;
+    this._initPromise = null;
+    this._isClosed = false;
+  }
+
+  /**
+   * Get the version of the library.
+   * @returns {String} the version of the library.
+   */
+  static getVersion() {
+    return LbugNative.NodeDatabase.getVersion();
+  }
+
+  /**
+   * Get the storage version of the library.
+   * @returns {Number} the storage version of the library.
+   */
+  static getStorageVersion() {
+    return LbugNative.NodeDatabase.getStorageVersion();
+  }
+
+  /**
+   * Initialize the database. Calling this function is optional, as the
+   * database is initialized automatically when the first query is executed.
+   */
+  async init() {
+    if (!this._isInitialized) {
+      if (!this._initPromise) {
+        this._initPromise = new Promise((resolve, reject) => {
+          this._database.initAsync((err) => {
+            if (err) {
+              reject(err);
+            } else {
+              try {
+                this._isInitialized = true;
+              } catch (e) {
+                return reject(e);
+              }
+              resolve();
+            }
+          });
+        });
+      }
+      await this._initPromise;
+      this._initPromise = null;
+    }
+  }
+
+  /**
+   * Initialize the database synchronously. Calling this function is optional, as the
+   * database is initialized automatically when the first query is executed. This function
+   * may block the main thread, so use it with caution.
+   */
+  initSync() {
+    if (this._initPromise) {
+      throw new Error("There is an ongoing asynchronous initialization. Please wait for it to finish.");
+    }
+    if (this._isInitialized) {
+      return;
+    }
+    this._database.initSync();
+    this._isInitialized = true;
+  }
+
+  /**
+   * Internal function to get the underlying native database object.
+   * @returns {LbugNative.NodeDatabase} the underlying native database.
+   * @throws {Error} if the database is closed.
+   */
+  async _getDatabase() {
+    if (this._isClosed) {
+      throw new Error("Database is closed.");
+    }
+    await this.init();
+    return this._database;
+  }
+
+  /**
+   * Internal function to get the underlying native database object synchronously.
+   * @returns {LbugNative.NodeDatabase} the underlying native database.
+   * @throws {Error} if the database is closed.
+   */
+  _getDatabaseSync() {
+    if (this._isClosed) {
+      throw new Error("Database is closed.");
+    }
+    if (!this._isInitialized) {
+      this.initSync();
+    }
+    return this._database;
+  }
+
+  /**
+   * Close the database.
+   */
+  async close() {
+    if (this._isClosed) {
+      return;
+    }
+    if (!this._isInitialized) {
+      if (this._initPromise) {
+        // Database is initializing, wait for it to finish first.
+        await this._initPromise;
+      } else {
+        // Database is not initialized, simply mark it as closed and initialized.
+        this._isInitialized = true;
+        this._isClosed = true;
+        delete this._database;
+        return;
+      }
+    }
+    // Database is initialized, close it.
+    this._database.close();
+    delete this._database;
+    this._isClosed = true;
+  }
+
+  /**
+   * Close the database synchronously.
+   * @throws {Error} if there is an ongoing asynchronous initialization.
+   */
+  closeSync() {
+    if (this._isClosed) {
+      return;
+    }
+    if (!this._isInitialized) {
+      if (this._initPromise) {
+        throw new Error("There is an ongoing asynchronous initialization. Please wait for it to finish.");
+      } else {
+        this._isInitialized = true;
+        this._isClosed = true;
+        delete this._database;
+        return;
+      }
+    }
+    this._database.close();
+    delete this._database;
+    this._isClosed = true;
+  }
+}
+
+module.exports = Database;

package/index.js

@@ -0,0 +1,19 @@
+"use strict";
+
+const Connection = require("./connection.js");
+const Database = require("./database.js");
+const PreparedStatement = require("./prepared_statement.js");
+const QueryResult = require("./query_result.js");
+
+module.exports = {
+  Connection,
+  Database,
+  PreparedStatement,
+  QueryResult,
+  get VERSION() {
+    return Database.getVersion();
+  },
+  get STORAGE_VERSION() {
+    return Database.getStorageVersion();
+  },
+};

package/index.mjs

@@ -0,0 +1,10 @@
+import lbug from "./index.js";
+
+// Re-export everything from the CommonJS module
+export const Database = lbug.Database;
+export const Connection = lbug.Connection;
+export const PreparedStatement = lbug.PreparedStatement;
+export const QueryResult = lbug.QueryResult;
+export const VERSION = lbug.VERSION;
+export const STORAGE_VERSION = lbug.STORAGE_VERSION;
+export default lbug;

package/lbug.d.ts

@@ -0,0 +1,399 @@
+
+/**
+ * A nullable type that can be either T or null.
+ */
+export type Nullable<T> = T | null;
+
+/**
+ * A callback function pattern used throughout the API.
+ * @template T The type of the result value (defaults to void)
+ */
+export type Callback<T = void> = (error: Error | null, result?: T) => void;
+
+/**
+ * Callback for query execution progress updates.
+ * @param pipelineProgress Progress of the current pipeline (0-100)
+ * @param numPipelinesFinished Number of pipelines completed
+ * @param numPipelines Total number of pipelines
+ */
+export type ProgressCallback = (
+    pipelineProgress: number,
+    numPipelinesFinished: number,
+    numPipelines: number
+) => void;
+
+/**
+ * Represents a node ID in the graph database.
+ */
+export interface NodeID {
+    /** The offset of the node in its table */
+    offset: number;
+    /** The table ID the node belongs to */
+    table: number;
+}
+
+/**
+ * Represents a node value in the graph.
+ */
+export interface NodeValue {
+    /** The label of the node (type) */
+    _label: string | null;
+    /** The ID of the node */
+    _id: NodeID | null;
+    /** Additional properties of the node */
+    [key: string]: any;
+}
+
+/**
+ * Represents a relationship (edge) value in the graph.
+ */
+export interface RelValue {
+    /** The source node ID */
+    _src: NodeID | null;
+    /** The destination node ID */
+    _dst: NodeID | null;
+    /** The relationship type/label */
+    _label: string | null;
+    /** The relationship ID */
+    _id: any;
+    /** Additional properties of the relationship */
+    [key: string]: any;
+}
+
+/**
+ * Represents a recursive relationship value (path) in the graph.
+ */
+export interface RecursiveRelValue {
+    /** Array of nodes in the path */
+    _nodes: any[];
+    /** Array of relationships in the path */
+    _rels: any[];
+}
+
+/**
+ * Union type representing all possible value types in Lbug.
+ */
+export type LbugValue =
+    | null
+    | boolean
+    | number
+    | bigint
+    | string
+    | Date
+    | NodeValue
+    | RelValue
+    | RecursiveRelValue
+    | LbugValue[]
+    | { [key: string]: LbugValue };
+
+/**
+ * Configuration options for the database system.
+ */
+export interface SystemConfig {
+    /** Size of the buffer pool in bytes */
+    bufferPoolSize?: number;
+    /** Whether to enable compression */
+    enableCompression?: boolean;
+    /** Whether to open the database in read-only mode */
+    readOnly?: boolean;
+    /** Maximum size of the database in bytes */
+    maxDBSize?: number;
+    /** Whether to enable automatic checkpoints */
+    autoCheckpoint?: boolean;
+    /** Threshold for automatic checkpoints */
+    checkpointThreshold?: number;
+}
+
+/**
+ * Represents a Lbug database instance.
+ */
+export class Database {
+    /**
+     * Constructs a new Database instance.
+     * @param databasePath Path to the database directory (defaults to ":memory:")
+     * @param bufferManagerSize Size of the buffer manager in bytes
+     * @param enableCompression Whether to enable compression
+     * @param readOnly Whether to open in read-only mode
+     * @param maxDBSize Maximum size of the database in bytes
+     * @param autoCheckpoint Whether to enable automatic checkpoints
+     * @param checkpointThreshold Threshold for automatic checkpoints
+     */
+    constructor(
+        databasePath?: string,
+        bufferManagerSize?: number,
+        enableCompression?: boolean,
+        readOnly?: boolean,
+        maxDBSize?: number,
+        autoCheckpoint?: boolean,
+        checkpointThreshold?: number
+    );
+
+    /**
+     * Initialize the database. Calling this function is optional, as the
+     * database is initialized automatically when the first query is executed.
+     * @returns Promise that resolves when initialization completes
+     */
+    init(): Promise<void>;
+
+    /**
+     * Initialize the database synchronously. Calling this function is optional, as the
+     * database is initialized automatically when the first query is executed. This function
+     * may block the main thread, so use it with caution.
+     */
+    initSync(): void;
+
+    /**
+     * Close the database and release resources.
+     * @returns Promise that resolves when database is closed
+     */
+    close(): Promise<void>;
+
+    /**
+     * Close the database synchronously.
+     */
+    closeSync(): void;
+
+    /**
+     * Get the version of the Lbug library.
+     * @returns The version string of the library
+     */
+    static getVersion(): string;
+
+    /**
+     * Get the storage version of the Lbug library.
+     * @returns The storage version of the library
+     */
+    static getStorageVersion(): number;
+}
+
+/**
+ * Represents a connection to a Lbug database.
+ */
+export class Connection {
+    /**
+     * Creates a new connection to the specified database.
+     * @param database The database instance to connect to
+     * @param numThreads Optional maximum number of threads for query execution
+     */
+    constructor(database: Database, numThreads?: number);
+
+    /**
+     * Initialize the connection.
+     * @returns Promise that resolves when initialization completes
+     */
+    init(): Promise<void>;
+
+    /**
+     * Initialize the connection synchronously. This function may block the main thread, so use it with caution.
+     */
+    initSync(): void;
+
+    /**
+     * Set the maximum number of threads for query execution.
+     * @param numThreads The number of threads to use
+     */
+    setMaxNumThreadForExec(numThreads: number): void;
+
+    /**
+     * Set the query timeout in milliseconds.
+     * @param timeoutInMs Timeout in milliseconds
+     */
+    setQueryTimeout(timeoutInMs: number): void;
+
+    /**
+     * Close the connection.
+     * @returns Promise that resolves when connection is closed
+     */
+    close(): Promise<void>;
+
+    /**
+     * Close the connection synchronously.
+     */
+    closeSync(): void;
+
+    /**
+     * Execute a prepared statement.
+     * @param preparedStatement The prepared statement to execute
+     * @param params Parameters for the query as a plain object
+     * @param progressCallback Optional progress callback
+     * @returns Promise that resolves to the query result(s)
+     */
+    execute(
+        preparedStatement: PreparedStatement,
+        params?: Record<string, LbugValue>,
+        progressCallback?: ProgressCallback
+    ): Promise<QueryResult | QueryResult[]>;
+
+    /**
+     * Execute a prepared statement synchronously.
+     * @param preparedStatement The prepared statement to execute
+     * @param params Parameters for the query as a plain object
+     * @returns The query result(s)
+     */
+    executeSync(
+        preparedStatement: PreparedStatement,
+        params?: Record<string, LbugValue>
+    ): QueryResult | QueryResult[];
+
+    /**
+     * Prepare a statement for execution.
+     * @param statement The statement to prepare
+     * @returns Promise that resolves to the prepared statement
+     */
+    prepare(statement: string): Promise<PreparedStatement>;
+
+    /**
+     * Prepare a statement for execution synchronously.
+     * @param statement The statement to prepare
+     * @returns The prepared statement
+     */
+    prepareSync(statement: string): PreparedStatement;
+
+    /**
+     * Execute a query.
+     * @param statement The statement to execute
+     * @param progressCallback Optional progress callback
+     * @returns Promise that resolves to the query result(s)
+     */
+    query(
+        statement: string,
+        progressCallback?: ProgressCallback
+    ): Promise<QueryResult | QueryResult[]>;
+
+    /**
+     * Execute a query synchronously.
+     * @param statement The statement to execute
+     * @returns The query result(s)
+     */
+    querySync(statement: string): QueryResult | QueryResult[];
+}
+
+/**
+ * Represents a prepared statement for efficient query execution.
+ * Note: This class is created internally by Connection.prepare() methods.
+ */
+export class PreparedStatement {
+    /**
+     * Check if the statement was prepared successfully.
+     * @returns True if preparation was successful
+     */
+    isSuccess(): boolean;
+
+    /**
+     * Get the error message if preparation failed.
+     * @returns The error message or empty string if successful
+     */
+    getErrorMessage(): string;
+}
+
+/**
+ * Represents the results of a query execution.
+ * Note: This class is created internally by Connection query methods.
+ */
+export class QueryResult {
+    /**
+     * Reset the iterator for reading results.
+     */
+    resetIterator(): void;
+
+    /**
+     * Check if there are more rows to read.
+     * @returns True if more rows are available
+     */
+    hasNext(): boolean;
+
+    /**
+     * Get the number of tuples (rows) in the result.
+     * @returns The number of rows
+     */
+    getNumTuples(): number;
+
+    /**
+     * Get the next row.
+     * @returns Promise that resolves to the next row or null if no more rows
+     */
+    getNext(): Promise<Record<string, LbugValue> | null>;
+
+    /**
+     * Get the next row synchronously.
+     * @returns The next row or null if no more rows
+     */
+    getNextSync(): Record<string, LbugValue> | null;
+
+    /**
+     * Iterate through the query result with callback functions.
+     * @param resultCallback Callback function called for each row
+     * @param doneCallback Callback function called when iteration is done
+     * @param errorCallback Callback function called when there is an error
+     */
+    each(
+        resultCallback: (row: Record<string, LbugValue>) => void,
+        doneCallback: () => void,
+        errorCallback: (error: Error) => void
+    ): void;
+
+    /**
+     * Get all rows of the query result.
+     * @returns Promise that resolves to all rows
+     */
+    getAll(): Promise<Record<string, LbugValue>[]>;
+
+    /**
+     * Get all rows of the query result synchronously.
+     * @returns All rows of the query result
+     */
+    getAllSync(): Record<string, LbugValue>[];
+
+    /**
+     * Get all rows of the query result with callback functions.
+     * @param resultCallback Callback function called with all rows
+     * @param errorCallback Callback function called when there is an error
+     */
+    all(
+        resultCallback: (rows: Record<string, LbugValue>[]) => void,
+        errorCallback: (error: Error) => void
+    ): void;
+
+    /**
+     * Get the column data types.
+     * @returns Promise that resolves to array of data type strings
+     */
+    getColumnDataTypes(): Promise<string[]>;
+
+    /**
+     * Get the column data types synchronously.
+     * @returns Array of data type strings
+     */
+    getColumnDataTypesSync(): string[];
+
+    /**
+     * Get the column names.
+     * @returns Promise that resolves to array of column names
+     */
+    getColumnNames(): Promise<string[]>;
+
+    /**
+     * Get the column names synchronously.
+     * @returns Array of column names
+     */
+    getColumnNamesSync(): string[];
+
+    /**
+     * Close the result set and release resources.
+     */
+    close(): void;
+}
+
+/**
+ * Default export for the Lbug module.
+ */
+declare const lbug: {
+    Database: typeof Database;
+    Connection: typeof Connection;
+    PreparedStatement: typeof PreparedStatement;
+    QueryResult: typeof QueryResult;
+    VERSION: string;
+    STORAGE_VERSION: bigint;
+};
+
+export default lbug;

package/lbug_native.js

@@ -0,0 +1,25 @@
+/**
+ * This file is a customized loader for the lbugjs.node native module.
+ * It is used to load the native module with the correct flags on Linux so that
+ * extension loading works correctly.
+ * @module lbug_native
+ * @private
+ */
+
+const process = require("process");
+const constants = require("constants");
+const join = require("path").join;
+
+const lbugNativeModule = { exports: {} };
+const modulePath = join(__dirname, "lbugjs.node");
+if (process.platform === "linux") {
+  process.dlopen(
+    lbugNativeModule,
+    modulePath,
+    constants.RTLD_LAZY | constants.RTLD_GLOBAL
+  );
+} else {
+  process.dlopen(lbugNativeModule, modulePath);
+}
+
+module.exports = lbugNativeModule.exports;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ladybugdb/core-linux-arm64",
+  "version": "0.15.2",
+  "description": "An in-process property graph database management system built for query speed and scalability.",
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LadybugDB/ladybug.git"
+  },
+  "files": [
+    "connection.js",
+    "database.js",
+    "index.js",
+    "index.mjs",
+    "lbug.d.ts",
+    "lbug_native.js",
+    "prepared_statement.js",
+    "query_result.js",
+    "lbugjs.node",
+    "LICENSE",
+    "README.md"
+  ]
+}