falkordb 6.6.2 → 6.8.0

package/README.md

@@ -32,12 +32,10 @@ npm install falkordb
 import { FalkorDB } from 'falkordb';
 
 const db = await FalkorDB.connect({
+    host: 'localhost',
+    port: 6379,
     username: 'myUsername',
-    password: 'myPassword',
-    socket: {
-        host: 'localhost',
-        port: 6379
-    }
+    password: 'myPassword'
 })
 
 console.log('Connected to FalkorDB')
@@ -62,6 +60,50 @@ db.close()
 
 To learn more about Cypher query language check: https://docs.falkordb.com/cypher/
 
+### Connection Options
+
+`host` and `port` are the shorthand for a plain TCP connection and default to `localhost:6379`.
+You can also pass a connection URL:
+
+```typescript
+const db = await FalkorDB.connect({ url: 'falkor://localhost:6379' })
+```
+
+For anything beyond host and port — TLS, connection timeouts, keep-alive — use `socket`, which is
+passed to the underlying [node-redis](https://github.com/redis/node-redis) client:
+
+```typescript
+const db = await FalkorDB.connect({
+    socket: {
+        host: 'localhost',
+        port: 6379,
+        tls: true,
+        connectTimeout: 5000
+    }
+})
+```
+
+`url` sets the connection address, so it overrides the top-level `host` and `port`. Other
+`socket` settings such as TLS and timeouts still apply alongside it. When both are given,
+`socket.host` and `socket.port` take precedence over the top-level `host` and `port`.
+
+#### `.stubs()`
+
+Lists the graphs that are currently offloaded to disk ("stubs"). `db.list()` already includes
+offloaded graphs, so `stubs()` is how you tell which of the listed graphs are not loaded in memory.
+
+`GRAPH.STUBS` is provided by the FalkorDB Enterprise graph-offloading module, so on deployments
+without that module the call rejects with an "unknown command" error — treat that as
+"offloading is not supported here".
+
+On a cluster the replies of all master nodes are combined. If only some masters fail, the
+partial result is returned and the failures are logged; the call rejects only when every
+master fails.
+
+```typescript
+const offloaded = await db.stubs();
+```
+
 #### `.close()`
 
 Forcibly close a client's connection to FalkorDB immediately. Calling `close` will not send further pending commands to the Redis server, or wait for or parse outstanding responses.

package/dist/src/clients/client.d.ts

@@ -8,6 +8,14 @@ import { UdfListReply } from "../commands/UDF_LIST";
 export interface Client {
     init(falkordb: FalkorDB): Promise<void>;
     list(): Promise<Array<string>>;
+    /**
+     * Lists the graphs that are currently offloaded to disk ("stubs").
+     *
+     * `GRAPH.STUBS` is provided by the FalkorDB Enterprise graph-offloading
+     * module, so it rejects with an "unknown command" error on deployments where
+     * that module is not loaded.
+     */
+    stubs(): Promise<Array<string>>;
     configGet(configKey: string): Promise<(string | number)[] | (string | number)[][]>;
     configSet(configKey: string, value: number | string): Promise<void>;
     info(section?: string): Promise<(string | string[])[]>;

package/dist/src/clients/cluster.d.ts

@@ -41,6 +41,7 @@ export declare class Cluster implements Client {
     delete(graph: string): Promise<void>;
     explain(graph: string, query: string): Promise<string[]>;
     list(): Promise<Array<string>>;
+    stubs(): Promise<Array<string>>;
     configGet(configKey: string): Promise<(string | number)[] | (string | number)[][]>;
     configSet(configKey: string, value: number | string): Promise<void>;
     info(section?: string): Promise<(string | string[])[]>;

package/dist/src/clients/cluster.js

@@ -59,6 +59,30 @@ class Cluster {
         }
         return result;
     }
+    async stubs() {
+        const replies = await Promise.allSettled(this.#client.masters.map(async (master) => {
+            return (await this.#client.nodeClient(master)).falkordb.stubs();
+        }));
+        const result = [];
+        const errors = [];
+        for (const reply of replies) {
+            if (reply.status === "fulfilled") {
+                result.push(...reply.value);
+            }
+            else {
+                errors.push(reply.reason);
+            }
+        }
+        // Only surface a failure when every master failed - e.g. when the
+        // graph-offloading module is missing cluster-wide ("unknown command").
+        if (errors.length > 0 && errors.length === replies.length) {
+            throw errors[0];
+        }
+        if (errors.length > 0) {
+            console.error("Some nodes failed to respond:", errors);
+        }
+        return result;
+    }
     async configGet(configKey) {
         return this.#client.falkordb.configGet(configKey);
     }

package/dist/src/clients/nullClient.d.ts

@@ -21,6 +21,7 @@ export declare class NullClient implements Client {
     getConnection(): Promise<SingleGraphConnection>;
     init(_falkordb: FalkorDB): Promise<void>;
     list(): Promise<Array<string>>;
+    stubs(): Promise<Array<string>>;
     configGet(_configKey: string): Promise<(string | number)[] | (string | number)[][]>;
     configSet(_configKey: string, _value: number | string): Promise<void>;
     info(_section?: string): Promise<(string | string[])[]>;

package/dist/src/clients/nullClient.js

@@ -22,6 +22,9 @@ class NullClient {
     list() {
         throw new Error("Method not implemented.");
     }
+    stubs() {
+        throw new Error("Method not implemented.");
+    }
     configGet(_configKey) {
         throw new Error("Method not implemented.");
     }

package/dist/src/clients/single.d.ts

@@ -35,6 +35,7 @@ export declare class Single implements Client {
     explain(graph: string, query: string): Promise<string[]>;
     profile<_T>(graph: string, query: string): Promise<string[]>;
     list(): Promise<string[]>;
+    stubs(): Promise<string[]>;
     configGet(configKey: string): Promise<(string | number)[] | (string | number)[][]>;
     configSet(configKey: string, value: number | string): Promise<void>;
     info(section?: string): Promise<(string | string[])[]>;

package/dist/src/clients/single.js

@@ -28,6 +28,9 @@ class Single {
     async list() {
         return this.client.falkordb.list();
     }
+    async stubs() {
+        return this.client.falkordb.stubs();
+    }
     async configGet(configKey) {
         return this.client.falkordb.configGet(configKey);
     }

package/dist/src/commands/STUBS.d.ts

@@ -0,0 +1,5 @@
+import { CommandParser } from '@redis/client';
+export declare const IS_READ_ONLY = true;
+export declare function parseCommand(parser: CommandParser): void;
+export declare function transformArguments(): Array<string>;
+export declare function transformReply(reply: unknown): Array<string>;

package/dist/src/commands/STUBS.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IS_READ_ONLY = void 0;
+exports.parseCommand = parseCommand;
+exports.transformArguments = transformArguments;
+exports.transformReply = transformReply;
+exports.IS_READ_ONLY = true;
+function parseCommand(parser) {
+    parser.push('GRAPH.STUBS');
+}
+function transformArguments() {
+    return ['GRAPH.STUBS'];
+}
+function transformReply(reply) {
+    return reply;
+}

package/dist/src/commands/index.d.ts

@@ -8,6 +8,7 @@ import * as PROFILE from './PROFILE';
 import * as QUERY from './QUERY';
 import * as RO_QUERY from './RO_QUERY';
 import * as SLOWLOG from './SLOWLOG';
+import * as STUBS from './STUBS';
 import * as CONSTRAINT_CREATE from './CONSTRAINT_CREATE';
 import * as CONSTRAINT_DROP from './CONSTRAINT_DROP';
 import * as COPY from './COPY';
@@ -40,6 +41,8 @@ declare const _default: {
     roQuery: typeof RO_QUERY;
     SLOWLOG: typeof SLOWLOG;
     slowLog: typeof SLOWLOG;
+    STUBS: typeof STUBS;
+    stubs: typeof STUBS;
     CONSTRAINT_CREATE: typeof CONSTRAINT_CREATE;
     constraintCreate: typeof CONSTRAINT_CREATE;
     CONSTRAINT_DROP: typeof CONSTRAINT_DROP;

package/dist/src/commands/index.js

@@ -11,6 +11,7 @@ const PROFILE = require("./PROFILE");
 const QUERY = require("./QUERY");
 const RO_QUERY = require("./RO_QUERY");
 const SLOWLOG = require("./SLOWLOG");
+const STUBS = require("./STUBS");
 const CONSTRAINT_CREATE = require("./CONSTRAINT_CREATE");
 const CONSTRAINT_DROP = require("./CONSTRAINT_DROP");
 const COPY = require("./COPY");
@@ -42,6 +43,8 @@ exports.default = {
     roQuery: RO_QUERY,
     SLOWLOG,
     slowLog: SLOWLOG,
+    STUBS,
+    stubs: STUBS,
     CONSTRAINT_CREATE,
     constraintCreate: CONSTRAINT_CREATE,
     CONSTRAINT_DROP,

package/dist/src/falkordb.d.ts

@@ -46,6 +46,16 @@ export interface FalkorDBOptions {
      * Socket connection properties
      */
     socket?: SocketOptions;
+    /**
+     * Server hostname, shorthand for `socket.host`.
+     * Ignored when `url` or `socket.host` is provided.
+     */
+    host?: string;
+    /**
+     * Server port, shorthand for `socket.port`.
+     * Ignored when `url` or `socket.port` is provided.
+     */
+    port?: number;
     /**
      * ACL username ([see ACL guide](https://redis.io/topics/acl))
      */
@@ -82,6 +92,15 @@ export default class FalkorDB extends EventEmitter {
     selectGraph(graphId: string): Graph;
     get connection(): Promise<SingleGraphConnection>;
     list(): Promise<string[]>;
+    /**
+     * Lists the graphs that are currently offloaded to disk ("stubs").
+     *
+     * `GRAPH.STUBS` is provided by the FalkorDB Enterprise graph-offloading
+     * module, so this rejects with an "unknown command" error on deployments
+     * where that module is not loaded. Callers that support both editions
+     * should treat such a rejection as "no offloading support".
+     */
+    stubs(): Promise<string[]>;
     configGet(configKey: string): Promise<(string | number)[] | (string | number)[][]>;
     configSet(configKey: string, value: number | string): Promise<void>;
     info(section?: string): Promise<(string | string[])[]>;

package/dist/src/falkordb.js

@@ -21,7 +21,18 @@ async function clientFactory(client) {
 class FalkorDB extends events_1.EventEmitter {
     #client = new nullClient_1.NullClient();
     static async connect(options) {
-        const redisOption = (options ?? {});
+        const { host, port, ...rest } = options ?? {};
+        const redisOption = rest;
+        // Support the top-level `host`/`port` shorthand used by the other FalkorDB
+        // clients by folding them into the socket options node-redis expects.
+        // Explicit `socket` values win, and `url` takes precedence over both.
+        if (!redisOption.url && (host !== undefined || port !== undefined)) {
+            redisOption.socket = {
+                ...(host !== undefined && { host }),
+                ...(port !== undefined && { port }),
+                ...redisOption.socket,
+            };
+        }
         // If the URL is provided, and the protocol is `falkor` replaces it with `redis` for the underline redis client
         // e.g. falkor://localhost:6379 -> redis://localhost:6379
         if (redisOption.url && redisOption.url.startsWith('falkor')) {
@@ -53,6 +64,17 @@ class FalkorDB extends events_1.EventEmitter {
     async list() {
         return this.#client.list();
     }
+    /**
+     * Lists the graphs that are currently offloaded to disk ("stubs").
+     *
+     * `GRAPH.STUBS` is provided by the FalkorDB Enterprise graph-offloading
+     * module, so this rejects with an "unknown command" error on deployments
+     * where that module is not loaded. Callers that support both editions
+     * should treat such a rejection as "no offloading support".
+     */
+    async stubs() {
+        return this.#client.stubs();
+    }
     async configGet(configKey) {
         return this.#client.configGet(configKey);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "falkordb",
-  "version": "6.6.2",
+  "version": "6.8.0",
   "description": "A FalkorDB javascript library",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -33,19 +33,19 @@
     "falkordb"
   ],
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22"
   },
   "devDependencies": {
     "@tsconfig/node20": "^20.1.4",
-    "@types/jest": "^29.5.14",
+    "@types/jest": "^30.0.0",
     "@types/lodash": "^4.17.13",
-    "@types/node": "^25.0.2",
+    "@types/node": "^26.2.0",
     "@typescript-eslint/eslint-plugin": "^8.18.2",
     "@typescript-eslint/parser": "^8.18.2",
     "eslint": "^10.0.1",
     "gh-pages": "^6.2.0",
     "jest": "^30.2.0",
-    "release-it": "^19.0.3",
+    "release-it": "^21.0.2",
     "ts-jest": "^29.4.6",
     "typescript": "^5.9.3"
   },