speedkey 0.1.0

package/build-ts/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ *
+ * This entry point re-exports:
+ * - Native bindings auto-generated by napi-rs (moved to ./native.js)
+ * - All TypeScript client-side APIs from ./src/
+ */
+export * from "../build-ts/native";
+export * from "./BaseClient.js";
+export * from "./Batch.js";
+export * from "./Commands.js";
+export * from "./Errors.js";
+export * from "./GlideClient.js";
+export * from "./GlideClusterClient.js";
+export * from "./Logger.js";
+export * from "./OpenTelemetry.js";
+export * from "./server-modules/GlideFt.js";
+export * from "./server-modules/GlideFtOptions.js";
+export * from "./server-modules/GlideJson.js";

package/build-ts/index.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
+ *
+ * This entry point re-exports:
+ * - Native bindings auto-generated by napi-rs (moved to ./native.js)
+ * - All TypeScript client-side APIs from ./src/
+ */
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("../build-ts/native"), exports);
+// Export TypeScript APIs
+__exportStar(require("./BaseClient.js"), exports);
+__exportStar(require("./Batch.js"), exports);
+__exportStar(require("./Commands.js"), exports);
+__exportStar(require("./Errors.js"), exports);
+__exportStar(require("./GlideClient.js"), exports);
+__exportStar(require("./GlideClusterClient.js"), exports);
+__exportStar(require("./Logger.js"), exports);
+__exportStar(require("./OpenTelemetry.js"), exports);
+__exportStar(require("./server-modules/GlideFt.js"), exports);
+__exportStar(require("./server-modules/GlideFtOptions.js"), exports);
+__exportStar(require("./server-modules/GlideJson.js"), exports);

package/build-ts/native.d.ts

@@ -0,0 +1,286 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * This struct is used to keep track of the cursor of a cluster scan.
+ * We want to avoid passing the cursor between layers of the application,
+ * So we keep the state in the container and only pass the id of the cursor.
+ * The cursor is stored in the container and can be retrieved using the id.
+ * The cursor is removed from the container when the object is deleted (dropped).
+ * To create a cursor:
+ * ```typescript
+ * // For a new cursor
+ * let cursor = new ClusterScanCursor();
+ * // Using an existing id
+ * let cursor = new ClusterScanCursor("cursor_id");
+ * ```
+ * To get the cursor id:
+ * ```typescript
+ * let cursorId = cursor.getCursor();
+ * ```
+ * To check if the scan is finished:
+ * ```typescript
+ * let isFinished = cursor.isFinished(); // true if the scan is finished
+ * ```
+ */
+export declare class ClusterScanCursor {
+  constructor(newCursor?: string | undefined | null)
+  /** Returns the cursor id. */
+  getCursor(): string
+  /** Returns true if the scan is finished. */
+  isFinished(): boolean
+}
+
+/**
+ * A handle to a Glide client that allows sending commands directly via NAPI.
+ * The client is pinned to a dedicated worker thread for lock-free concurrent execution.
+ * Commands are sent via channel to the worker thread which executes them via spawn_local.
+ *
+ * Response Buffering Architecture:
+ * - Responses are pushed to a shared buffer instead of calling ThreadsafeFunction per-response
+ * - A wake-up callback is called ONCE when the buffer transitions from empty to non-empty
+ * - JS drains all responses from the buffer in a single call
+ */
+export declare class GlideClientHandle {
+  /**
+   * Sends a command to the Valkey/Redis server.
+   *
+   * This method is the core of the direct NAPI layer. It:
+   * 1. Checks inflight request limits synchronously
+   * 2. Reconstructs the command arguments from the pointer
+   * 3. Spawns an async task to execute the command
+   * 4. Calls the response callback with the result
+   *
+   * # Arguments
+   * * `callback_idx` - Index to identify this request in JavaScript
+   * * `request_type` - The type of Redis command (maps to RequestType enum)
+   * * `args_pointer_high` - High 32 bits of the args Vec<Bytes> pointer
+   * * `args_pointer_low` - Low 32 bits of the args Vec<Bytes> pointer
+   * * `route_bytes` - Optional routing information for cluster mode
+   *
+   * # Returns
+   * * `true` if the command was successfully queued
+   * * `false` if the inflight request limit was exceeded
+   */
+  sendCommand(callbackIdx: number, requestType: number, argsPointerHigh: number, argsPointerLow: number, routeBytes?: Uint8Array | undefined | null): boolean
+  /**
+   * Drains all pending responses from the buffer.
+   * This should be called from JS when the wake callback is triggered.
+   */
+  drainResponses(): Array<CommandResponse>
+  /**
+   * Closes the client connection.
+   * After calling this, the client handle should not be used.
+   * This marks the buffer as closed to prevent any further wake-up callbacks,
+   * which prevents use-after-free crashes during shutdown.
+   */
+  close(): void
+  /**
+   * Returns the number of available inflight request slots.
+   * This can be used to check if more commands can be sent.
+   */
+  availableInflightSlots(): number
+  /**
+   * Sends a batch of commands to the Valkey/Redis server.
+   *
+   * # Arguments
+   * * `callback_idx` - Index to identify this request in JavaScript
+   * * `commands` - Array of command tuples (request_type, args_pointer_high, args_pointer_low)
+   * * `is_atomic` - If true, execute as transaction (MULTI/EXEC); if false, as pipeline
+   * * `raise_on_error` - Whether to raise error on first failure
+   * * `timeout` - Optional timeout in milliseconds
+   *
+   * # Returns
+   * * `true` if the batch was successfully queued
+   * * `false` if the inflight request limit was exceeded
+   */
+  sendBatch(callbackIdx: number, commands: Array<BatchCommand>, isAtomic: boolean, raiseOnError: boolean, timeout?: number | undefined | null, retryServerError?: boolean | undefined | null, retryConnectionError?: boolean | undefined | null, routeBytes?: Uint8Array | undefined | null): boolean
+  /** Invokes a Lua script using EVALSHA with automatic LOAD fallback. */
+  invokeScript(callbackIdx: number, hash: string, keysPointerHigh: number, keysPointerLow: number, argsPointerHigh: number, argsPointerLow: number, routeBytes?: Uint8Array | undefined | null): boolean
+  /** Performs cluster-wide key scanning. */
+  clusterScan(callbackIdx: number, cursor: string, matchPattern?: Uint8Array | undefined | null, count?: number | undefined | null, objectType?: string | undefined | null, allowNonCoveredSlots?: boolean | undefined | null): boolean
+  /** Updates the connection password. */
+  updateConnectionPassword(callbackIdx: number, password: string | undefined | null, immediateAuth: boolean): boolean
+  /** Refreshes the IAM token. */
+  refreshIamToken(callbackIdx: number): boolean
+}
+
+/**
+ * A wrapper for a script object. As long as this object is alive, the script's code is saved in memory, and can be resent to the server.
+ *
+ * **IMPORTANT**: Script objects are NOT automatically garbage collected. You are responsible for calling `release()`
+ * on every Script object when you're done with it to prevent memory leaks. Failure to do so will result in memory leaks.
+ */
+export declare class Script {
+  /** Construct with the script's code. */
+  constructor(code: string | Uint8Array)
+  /** Returns the hash of the script. */
+  getHash(): string
+  /**
+   * Decrements the script's reference count in the local container.
+   * Removes the script when the count reaches zero.
+   *
+   * You need to call this method when you're done with the Script object. Script objects are NOT
+   * automatically garbage collected, and failure to call release() will result in memory leaks.
+   */
+  release(): void
+}
+
+/** A single command in a batch */
+export interface BatchCommand {
+  requestType: number
+  argsPointerHigh: number
+  argsPointerLow: number
+}
+
+/**
+ * Response object passed to the JavaScript callback for command results.
+ * This replaces the protobuf-based response used in the socket IPC layer.
+ */
+export interface CommandResponse {
+  /** The callback index that identifies this request on the JS side */
+  callbackIdx: number
+  /** High 32 bits of the response value pointer (if response is a Value) */
+  respPointerHigh?: number
+  /** Low 32 bits of the response value pointer (if response is a Value) */
+  respPointerLow?: number
+  /** Constant response string (e.g., "OK" for simple responses) */
+  constantResponse?: string
+  /** Error information if the request failed */
+  requestError?: RequestErrorNapi
+  /** Closing error message if the client is closing */
+  closingError?: string
+  /** Whether this is a push message (pub/sub) */
+  isPush: boolean
+}
+
+/**
+ * Creates a new direct NAPI client connection with response buffering.
+ *
+ * This function creates a Client using the glide-core library and wraps it
+ * in a GlideClientHandle that can send commands directly without socket IPC.
+ *
+ * Response Buffering:
+ * - Responses are accumulated in a shared buffer
+ * - A single wake-up callback notifies JS when responses are available
+ * - JS then calls drainResponses() to get all pending responses at once
+ * - This reduces ThreadsafeFunction call overhead from N to ~1 per batch
+ *
+ * # Arguments
+ * * `connection_request_bytes` - Protobuf-encoded ConnectionRequest
+ * * `wake_callback` - JavaScript callback to wake up when responses available
+ *
+ * # Returns
+ * A Promise that resolves to a GlideClientHandle on success
+ */
+export declare function CreateDirectClient(connectionRequestBytes: Uint8Array, wakeCallback: () => void): Promise<GlideClientHandle>
+
+/** Creates an open telemetry span with the given name and returns a pointer to the span */
+export declare function createLeakedOtelSpan(name: string): [number, number]
+
+/**
+ * @internal @test
+ * This function is for tests that require a value allocated on the heap.
+ * Should NOT be used in production.
+ */
+export declare function createLeakedStringVec(message: Array<Uint8Array>): [number, number]
+
+export const DEFAULT_CONNECTION_TIMEOUT_IN_MILLISECONDS: number
+
+export const DEFAULT_INFLIGHT_REQUESTS_LIMIT: number
+
+export const DEFAULT_REQUEST_TIMEOUT_IN_MILLISECONDS: number
+
+export declare function dropOtelSpan(spanPtr: bigint): void
+
+/**
+ * Free a previously leaked string vec by its split pointer.
+ * Called from JS to reclaim memory when a leaked pointer will not be
+ * passed to send_command/send_batch/invoke_script (e.g., early error paths).
+ */
+export declare function freeLeakedStringVec(highBits: number, lowBits: number): void
+
+export declare function getStatistics(): object
+
+export declare function InitInternalLogger(level?: Level | undefined | null, fileName?: string | undefined | null): Level
+
+export declare function InitOpenTelemetry(openTelemetryConfig: OpenTelemetryConfig): void
+
+export declare const enum Level {
+  Debug = 3,
+  Error = 0,
+  Info = 2,
+  Trace = 4,
+  Warn = 1,
+  Off = 5
+}
+
+export declare function log(logLevel: Level, logIdentifier: string, message: string): void
+
+export const MAX_REQUEST_ARGS_LEN: number
+
+/**
+ * Configuration for OpenTelemetry integration in the Node.js client.
+ *
+ * This struct allows you to configure how telemetry data (traces and metrics) is exported to an OpenTelemetry collector.
+ * - `traces`: Optional configuration for exporting trace data. If `None`, trace data will not be exported.
+ * - `metrics`: Optional configuration for exporting metrics data. If `None`, metrics data will not be exported.
+ * - `flush_interval_ms`: Optional interval in milliseconds between consecutive exports of telemetry data. If `None`, a default value will be used.
+ *
+ * At least one of traces or metrics must be provided.
+ */
+export interface OpenTelemetryConfig {
+  /** Optional configuration for exporting trace data. If `None`, trace data will not be exported. */
+  traces?: OpenTelemetryTracesConfig
+  /** Optional configuration for exporting metrics data. If `None`, metrics data will not be exported. */
+  metrics?: OpenTelemetryMetricsConfig
+  /** Optional interval in milliseconds between consecutive exports of telemetry data. If `None`, the default `DEFAULT_FLUSH_SIGNAL_INTERVAL_MS` will be used. */
+  flushIntervalMs?: number
+}
+
+/**
+ * Configuration for exporting OpenTelemetry metrics.
+ *
+ * - `endpoint`: The endpoint to which metrics data will be exported. Expected format:
+ *   - For gRPC: `grpc://host:port`
+ *   - For HTTP: `http://host:port` or `https://host:port`
+ *   - For file exporter: `file:///absolute/path/to/folder/file.json`
+ */
+export interface OpenTelemetryMetricsConfig {
+  /** The endpoint to which metrics data will be exported. */
+  endpoint: string
+}
+
+/**
+ * Configuration for exporting OpenTelemetry traces.
+ *
+ * - `endpoint`: The endpoint to which trace data will be exported. Expected format:
+ *   - For gRPC: `grpc://host:port`
+ *   - For HTTP: `http://host:port` or `https://host:port`
+ *   - For file exporter: `file:///absolute/path/to/folder/file.json`
+ * - `sample_percentage`: The percentage of requests to sample and create a span for, used to measure command duration. If `None`, a default value DEFAULT_TRACE_SAMPLE_PERCENTAGE will be used.
+ *   Note: There is a tradeoff between sampling percentage and performance. Higher sampling percentages will provide more detailed telemetry data but will impact performance.
+ *   It is recommended to keep this number low (1-5%) in production environments unless you have specific needs for higher sampling rates.
+ */
+export interface OpenTelemetryTracesConfig {
+  /** The endpoint to which trace data will be exported. */
+  endpoint: string
+  /**
+   * The percentage of requests to sample and create a span for, used to measure command duration. If `None`, a default value DEFAULT_TRACE_SAMPLE_PERCENTAGE will be used.
+   * Note: There is a tradeoff between sampling percentage and performance. Higher sampling percentages will provide more detailed telemetry data but will impact performance.
+   * It is recommended to keep this number low (1-5%) in production environments unless you have specific needs for higher sampling rates.
+   */
+  samplePercentage?: number
+}
+
+/** Error information for failed requests. */
+export interface RequestErrorNapi {
+  /** Human-readable error message */
+  message: string
+  /**
+   * Error type code (maps to RequestErrorType enum)
+   * 0 = Unspecified, 1 = ExecAbort, 2 = Timeout, 3 = Disconnect
+   */
+  errorType: number
+}
+
+export declare function valueFromSplitPointer(highBits: number, lowBits: number, stringDecoder: boolean): null | string | Uint8Array | number | {} | Boolean | BigInt | Set<any> | any[] | Buffer