@ladybugdb/core-darwin-arm64 0.17.0-dev.20260528 → 0.17.0

package/connection.js

@@ -2,6 +2,7 @@
 
 const LbugNative = require("./lbug_native.js");
 const QueryResult = require("./query_result.js");
+const { ArrowQueryResult } = require("./query_result.js");
 const PreparedStatement = require("./prepared_statement.js");
 
 class Connection {
@@ -320,6 +321,162 @@ class Connection {
     return this._unwrapMultipleQueryResultsSync(nodeQueryResult);
   }
 
+  /**
+   * Execute a query with the native Arrow result collector.
+   * @param {String} statement the statement to execute.
+   * @param {Number} chunkSize native Arrow chunk size.
+   * @returns {Promise<lbug.ArrowQueryResult>} a promise that resolves to the Arrow query result.
+   */
+  queryArrow(statement, chunkSize = 1000) {
+    return new Promise((resolve, reject) => {
+      if (typeof statement !== "string") {
+        return reject(new Error("statement must be a string."));
+      }
+      if (typeof chunkSize !== "number" || chunkSize <= 0) {
+        return reject(new Error("chunkSize must be a positive number."));
+      }
+      this._getConnection()
+        .then((connection) => {
+          const nodeQueryResult = new LbugNative.NodeQueryResult();
+          try {
+            connection.queryArrowAsync(statement, chunkSize, nodeQueryResult, (err) => {
+              if (err) {
+                return reject(err);
+              }
+              return resolve(new ArrowQueryResult(this, nodeQueryResult, chunkSize));
+            });
+          } catch (e) {
+            return reject(e);
+          }
+        })
+        .catch((err) => {
+          return reject(err);
+        });
+    });
+  }
+
+  /**
+   * Execute a query synchronously with the native Arrow result collector.
+   * @param {String} statement the statement to execute.
+   * @param {Number} chunkSize native Arrow chunk size.
+   * @returns {lbug.ArrowQueryResult} the Arrow query result.
+   */
+  queryArrowSync(statement, chunkSize = 1000) {
+    if (typeof statement !== "string") {
+      throw new Error("statement must be a string.");
+    }
+    if (typeof chunkSize !== "number" || chunkSize <= 0) {
+      throw new Error("chunkSize must be a positive number.");
+    }
+    const connection = this._getConnectionSync();
+    const nodeQueryResult = new LbugNative.NodeQueryResult();
+    connection.queryArrowSync(statement, chunkSize, nodeQueryResult);
+    return new ArrowQueryResult(this, nodeQueryResult, chunkSize);
+  }
+
+  /**
+   * Create an Arrow memory-backed node table from Arrow C Data Interface pointers.
+   * Ownership of the schema and arrays is transferred to Ladybug.
+   * @param {String} tableName the node table name to create.
+   * @param {BigInt|External} schemaPtr pointer to an ArrowSchema.
+   * @param {BigInt|External|Array<BigInt|External>} arraysPtr pointer to contiguous ArrowArray objects, or an array of ArrowArray pointers.
+   * @param {Number} numArrays number of ArrowArray batches when arraysPtr is contiguous.
+   * @returns {lbug.QueryResult} the table creation query result.
+   */
+  createArrowTableSync(tableName, schemaPtr, arraysPtr, numArrays = 1) {
+    if (typeof tableName !== "string") {
+      throw new Error("tableName must be a string.");
+    }
+    if (!Array.isArray(arraysPtr) && (typeof numArrays !== "number" || numArrays <= 0)) {
+      throw new Error("numArrays must be a positive number.");
+    }
+    const connection = this._getConnectionSync();
+    const nodeQueryResult = new LbugNative.NodeQueryResult();
+    connection.createArrowTableSync(tableName, schemaPtr, arraysPtr, numArrays, nodeQueryResult);
+    return new QueryResult(this, nodeQueryResult);
+  }
+
+  /**
+   * Create an Arrow memory-backed relationship table from Arrow C Data Interface pointers.
+   * For flat layout (default): the Arrow table must contain endpoint columns named "from" and "to".
+   * For CSR layout: pass indptrSchemaPtr and indptrArraysPtr; dstColName names the destination column.
+   * Ownership of the schema and arrays is transferred to Ladybug.
+   */
+  createArrowRelTableSync(
+    tableName,
+    srcTableName,
+    dstTableName,
+    schemaPtr,
+    arraysPtr,
+    numArrays = 1,
+    indptrSchemaPtr = null,
+    indptrArraysPtr = null,
+    numIndptrArrays = 1,
+    dstColName = "to"
+  ) {
+    if (typeof tableName !== "string") {
+      throw new Error("tableName must be a string.");
+    }
+    if (typeof srcTableName !== "string" || typeof dstTableName !== "string") {
+      throw new Error("srcTableName and dstTableName must be strings.");
+    }
+    if (!Array.isArray(arraysPtr) && (typeof numArrays !== "number" || numArrays <= 0)) {
+      throw new Error("numArrays must be a positive number.");
+    }
+    const connection = this._getConnectionSync();
+    const nodeQueryResult = new LbugNative.NodeQueryResult();
+    if (indptrSchemaPtr != null) {
+      if (indptrArraysPtr == null) {
+        throw new Error("indptrArraysPtr must be provided in CSR mode.");
+      }
+      if (!Array.isArray(indptrArraysPtr) && (!Number.isSafeInteger(numIndptrArrays) || numIndptrArrays <= 0)) {
+        throw new Error("numIndptrArrays must be a positive integer.");
+      }
+      if (typeof dstColName !== "string") {
+        throw new Error("dstColName must be a string.");
+      }
+      connection.createArrowRelTableSync(
+        tableName,
+        srcTableName,
+        dstTableName,
+        schemaPtr,
+        arraysPtr,
+        numArrays,
+        indptrSchemaPtr,
+        indptrArraysPtr,
+        numIndptrArrays,
+        dstColName,
+        nodeQueryResult
+      );
+    } else {
+      connection.createArrowRelTableSync(
+        tableName,
+        srcTableName,
+        dstTableName,
+        schemaPtr,
+        arraysPtr,
+        numArrays,
+        nodeQueryResult
+      );
+    }
+    return new QueryResult(this, nodeQueryResult);
+  }
+
+  /**
+   * Drop an Arrow memory-backed table and unregister its Arrow data.
+   * @param {String} tableName the Arrow table name.
+   * @returns {lbug.QueryResult} the drop query result.
+   */
+  dropArrowTableSync(tableName) {
+    if (typeof tableName !== "string") {
+      throw new Error("tableName must be a string.");
+    }
+    const connection = this._getConnectionSync();
+    const nodeQueryResult = new LbugNative.NodeQueryResult();
+    connection.dropArrowTableSync(tableName, nodeQueryResult);
+    return new QueryResult(this, nodeQueryResult);
+  }
+
   /**
    * Internal function to get the next query result for multiple query results.
    * @param {LbugNative.NodeQueryResult} nodeQueryResult the current node query result.

package/database.js

@@ -26,6 +26,7 @@ class Database {
    * the error occured.
    * @param {Boolean} enableChecksums If true, the database will use checksums to detect corruption in the
    * WAL file.
+   * @param {Boolean} enableDefaultHashIndex If true, node tables create the default primary-key hash index.
    */
   constructor(
     databasePath,
@@ -37,6 +38,7 @@ class Database {
     checkpointThreshold = -1,
     throwOnWalReplayFailure = true,
     enableChecksums = true,
+    enableDefaultHashIndex = true,
   ) {
     if (!databasePath) {
       databasePath = ":memory:";
@@ -65,7 +67,8 @@ class Database {
       autoCheckpoint,
       checkpointThreshold,
       throwOnWalReplayFailure,
-      enableChecksums
+      enableChecksums,
+      enableDefaultHashIndex
     );
     this._isInitialized = false;
     this._initPromise = null;

package/index.js

@@ -4,12 +4,25 @@ const Connection = require("./connection.js");
 const Database = require("./database.js");
 const PreparedStatement = require("./prepared_statement.js");
 const QueryResult = require("./query_result.js");
+const { ArrowQueryResult } = require("./query_result.js");
+
+function json(value) {
+  const stringValue = typeof value === "string" ? value : JSON.stringify(value);
+  return Object.freeze(
+    Object.defineProperties({}, {
+      _lbugType: { value: "JSON", enumerable: false },
+      value: { value: stringValue, enumerable: false },
+    })
+  );
+}
 
 module.exports = {
   Connection,
   Database,
   PreparedStatement,
   QueryResult,
+  ArrowQueryResult,
+  json,
   get VERSION() {
     return Database.getVersion();
   },

package/index.mjs

@@ -5,6 +5,8 @@ export const Database = lbug.Database;
 export const Connection = lbug.Connection;
 export const PreparedStatement = lbug.PreparedStatement;
 export const QueryResult = lbug.QueryResult;
+export const ArrowQueryResult = lbug.ArrowQueryResult;
+export const json = lbug.json;
 export const VERSION = lbug.VERSION;
 export const STORAGE_VERSION = lbug.STORAGE_VERSION;
 export default lbug;

package/lbug.d.ts

@@ -1,4 +1,3 @@
-
 /**
  * A nullable type that can be either T or null.
  */
@@ -22,6 +21,22 @@ export type ProgressCallback = (
     numPipelines: number
 ) => void;
 
+/**
+ * Low-level pointer to an Arrow C Data Interface struct.
+ * Native producers can pass N-API External values; JavaScript callers that have
+ * raw addresses can pass them as bigint.
+ */
+export type NativePointer = bigint | object;
+
+/**
+ * Zero-copy CSR arrays returned by an Arrow query result.
+ */
+export interface CSRResult {
+    indptr: BigUint64Array;
+    indices: BigUint64Array;
+    edgeIds: BigUint64Array | null;
+}
+
 /**
  * Represents a node ID in the graph database.
  */
@@ -84,6 +99,7 @@ export type LbugValue =
     | RelValue
     | RecursiveRelValue
     | LbugValue[]
+    | Map<LbugValue, LbugValue>
     | { [key: string]: LbugValue };
 
 /**
@@ -102,8 +118,15 @@ export interface SystemConfig {
     autoCheckpoint?: boolean;
     /** Threshold for automatic checkpoints */
     checkpointThreshold?: number;
+    /** Whether node tables create the default primary-key hash index */
+    enableDefaultHashIndex?: boolean;
 }
 
+/**
+ * Wrap a string or JavaScript value as a JSON-typed query parameter.
+ */
+export function json(value: string | LbugValue): LbugValue;
+
 /**
  * Represents a Lbug database instance.
  */
@@ -117,6 +140,9 @@ export class Database {
      * @param maxDBSize Maximum size of the database in bytes
      * @param autoCheckpoint Whether to enable automatic checkpoints
      * @param checkpointThreshold Threshold for automatic checkpoints
+     * @param throwOnWalReplayFailure Whether WAL replay failures should throw
+     * @param enableChecksums Whether checksum validation is enabled
+     * @param enableDefaultHashIndex Whether node tables create the default primary-key hash index
      */
     constructor(
         databasePath?: string,
@@ -125,7 +151,10 @@ export class Database {
         readOnly?: boolean,
         maxDBSize?: number,
         autoCheckpoint?: boolean,
-        checkpointThreshold?: number
+        checkpointThreshold?: number,
+        throwOnWalReplayFailure?: boolean,
+        enableChecksums?: boolean,
+        enableDefaultHashIndex?: boolean
     );
 
     /**
@@ -266,6 +295,56 @@ export class Connection {
      * @returns The query result(s)
      */
     querySync(statement: string): QueryResult | QueryResult[];
+
+    /**
+     * Execute a query with the native Arrow result collector.
+     * @param statement The statement to execute
+     * @param chunkSize Native Arrow chunk size
+     * @returns Promise that resolves to the Arrow query result
+     */
+    queryArrow(statement: string, chunkSize?: number): Promise<ArrowQueryResult>;
+
+    /**
+     * Execute a query synchronously with the native Arrow result collector.
+     * @param statement The statement to execute
+     * @param chunkSize Native Arrow chunk size
+     * @returns The Arrow query result
+     */
+    queryArrowSync(statement: string, chunkSize?: number): ArrowQueryResult;
+
+    /**
+     * Create an Arrow memory-backed node table from Arrow C Data Interface pointers.
+     * Ownership of schemaPtr and arraysPtr is transferred to Ladybug.
+     */
+    createArrowTableSync(
+        tableName: string,
+        schemaPtr: NativePointer,
+        arraysPtr: NativePointer | NativePointer[],
+        numArrays?: number
+    ): QueryResult;
+
+    /**
+     * Create an Arrow memory-backed relationship table from Arrow C Data Interface pointers.
+     * For flat layout (default): the Arrow table must contain endpoint columns named "from" and "to".
+     * For CSR layout: pass indptrSchemaPtr and indptrArraysPtr; dstColName names the destination column.
+     * Ownership of schemaPtr and arraysPtr is transferred to Ladybug.
+     */
+    createArrowRelTableSync(
+        tableName: string,
+        srcTableName: string,
+        dstTableName: string,
+        schemaPtr: NativePointer,
+        arraysPtr: NativePointer | NativePointer[],
+        numArrays?: number,
+        indptrSchemaPtr?: NativePointer | null,
+        indptrArraysPtr?: NativePointer | NativePointer[] | null,
+        numIndptrArrays?: number,
+        dstColName?: string): QueryResult;
+
+    /**
+     * Drop an Arrow memory-backed table and unregister its Arrow data.
+     */
+    dropArrowTableSync(tableName: string): QueryResult;
 }
 
 /**
@@ -279,6 +358,12 @@ export class PreparedStatement {
      */
     isSuccess(): boolean;
 
+    /**
+     * Check if the statement only performs read operations.
+     * @returns True if the prepared statement is read-only
+     */
+    isReadOnly(): boolean;
+
     /**
      * Get the error message if preparation failed.
      * @returns The error message or empty string if successful
@@ -384,6 +469,16 @@ export class QueryResult {
     close(): void;
 }
 
+/**
+ * Represents an Arrow-native query result.
+ */
+export class ArrowQueryResult extends QueryResult {
+    /**
+     * Get zero-copy native CSR arrays.
+     */
+    csr(): CSRResult;
+}
+
 /**
  * Default export for the Lbug module.
  */
@@ -392,6 +487,8 @@ declare const lbug: {
     Connection: typeof Connection;
     PreparedStatement: typeof PreparedStatement;
     QueryResult: typeof QueryResult;
+    ArrowQueryResult: typeof ArrowQueryResult;
+    json: typeof json;
     VERSION: string;
     STORAGE_VERSION: bigint;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ladybugdb/core-darwin-arm64",
-  "version": "0.17.0-dev.20260528",
+  "version": "0.17.0",
   "description": "An in-process property graph database management system built for query speed and scalability.",
   "os": [
     "darwin"

package/prepared_statement.js

@@ -30,6 +30,14 @@ class PreparedStatement {
     return this._preparedStatement.isSuccess();
   }
 
+  /**
+   * Check if the prepared statement only performs read operations.
+   * @returns {Boolean} true if the prepared statement is read-only.
+   */
+  isReadOnly() {
+    return this._preparedStatement.isReadOnly();
+  }
+
   /**
    * Get the error message if the prepared statement is not successfully prepared.
    * @returns {String} the error message.

package/query_result.js

@@ -239,4 +239,27 @@ class QueryResult {
   }
 }
 
+class ArrowQueryResult extends QueryResult {
+  /**
+   * Internal constructor. Use `Connection.queryArrow` or `Connection.queryArrowSync`.
+   * @param {Connection} connection the connection object.
+   * @param {LbugNative.NodeQueryResult} queryResult the native query result object.
+   * @param {Number} chunkSize native Arrow result chunk size.
+   */
+  constructor(connection, queryResult, chunkSize) {
+    super(connection, queryResult);
+    this._chunkSize = chunkSize;
+  }
+
+  /**
+   * Get zero-copy native CSR arrays from an Arrow query result.
+   * @returns {{indptr: BigUint64Array, indices: BigUint64Array, edgeIds: BigUint64Array|null}}
+   */
+  csr() {
+    this._checkClosed();
+    return this._queryResult.getCSRSync();
+  }
+}
+
 module.exports = QueryResult;
+module.exports.ArrowQueryResult = ArrowQueryResult;