commandkit 1.0.0-dev.20250702020504 → 1.0.0-dev.20250702033548

package/dist/kv/kv.d.ts

@@ -0,0 +1,321 @@
+import { DatabaseSync } from "node:sqlite";
+
+//#region src/kv/kv.d.ts
+
+/**
+ * Configuration options for the KV store
+ */
+interface KvOptions {
+  /** Enable Write-Ahead Logging for better performance and durability */
+  enableWAL?: boolean;
+  /** Namespace for the key-value store table */
+  namespace?: string;
+}
+/**
+ * A key-value store implementation using SQLite
+ *
+ * This class provides a simple, persistent key-value storage solution
+ * with support for namespaces, automatic cleanup, iteration, and expiration.
+ *
+ * @example
+ * ```typescript
+ * const kv = new KV('data.db');
+ * kv.set('user:123', JSON.stringify({ name: 'John', age: 30 }));
+ * const user = JSON.parse(kv.get('user:123') || '{}');
+ *
+ * // Using namespaces
+ * const userKv = kv.namespace('users');
+ * userKv.set('123', JSON.stringify({ name: 'John' }));
+ * ```
+ */
+declare class KV implements Disposable, AsyncDisposable {
+  private options;
+  private db;
+  private statements;
+  /**
+   * Creates a new KV store instance
+   *
+   * @param path - Database file path, buffer, URL, or existing DatabaseSync instance
+   * @param options - Configuration options for the KV store
+   */
+  constructor(path: string | Buffer | URL | DatabaseSync, options?: KvOptions);
+  /**
+   * Gets the current timestamp in milliseconds
+   */
+  private getCurrentTime;
+  /**
+   * Checks if the database connection is open
+   *
+   * @returns `true` if the database is open, `false` otherwise
+   */
+  isOpen(): boolean;
+  /**
+   * Gets the underlying SQLite database instance
+   *
+   * @returns The DatabaseSync instance
+   */
+  getDatabase(): DatabaseSync;
+  /**
+   * Closes the database connection
+   */
+  close(): void;
+  /**
+   * Disposable implementation - closes the database when disposed
+   */
+  [Symbol.dispose](): void;
+  /**
+   * AsyncDisposable implementation - closes the database when disposed
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+  /**
+   * Retrieves a value by key
+   *
+   * @param key - The key to retrieve
+   * @returns The value associated with the key, or `undefined` if not found or expired
+   *
+   * @example
+   * ```typescript
+   * const value = kv.get('my-key');
+   * if (value) {
+   *   console.log('Found:', value);
+   * }
+   * ```
+   */
+  get(key: string): string | undefined;
+  /**
+   * Sets a key-value pair
+   *
+   * @param key - The key to set
+   * @param value - The value to associate with the key
+   *
+   * @example
+   * ```typescript
+   * kv.set('user:123', JSON.stringify({ name: 'John' }));
+   * kv.set('counter', '42');
+   * ```
+   */
+  set(key: string, value: string): void;
+  /**
+   * Sets a key-value pair with expiration
+   *
+   * @param key - The key to set
+   * @param value - The value to associate with the key
+   * @param ttl - Time to live in milliseconds
+   *
+   * @example
+   * ```typescript
+   * // Set with 1 hour expiration
+   * kv.setex('session:123', 'user_data', 60 * 60 * 1000);
+   *
+   * // Set with 5 minutes expiration
+   * kv.setex('temp:data', 'cached_value', 5 * 60 * 1000);
+   * ```
+   */
+  setex(key: string, value: string, ttl: number): void;
+  /**
+   * Sets expiration for an existing key
+   *
+   * @param key - The key to set expiration for
+   * @param ttl - Time to live in milliseconds
+   * @returns `true` if the key exists and expiration was set, `false` otherwise
+   *
+   * @example
+   * ```typescript
+   * kv.set('user:123', 'user_data');
+   *
+   * // Set 30 minute expiration
+   * if (kv.expire('user:123', 30 * 60 * 1000)) {
+   *   console.log('Expiration set successfully');
+   * }
+   * ```
+   */
+  expire(key: string, ttl: number): boolean;
+  /**
+   * Gets the time to live for a key
+   *
+   * @param key - The key to check
+   * @returns Time to live in milliseconds, or `-1` if the key doesn't exist, or `-2` if the key has no expiration
+   *
+   * @example
+   * ```typescript
+   * const ttl = kv.ttl('user:123');
+   * if (ttl > 0) {
+   *   console.log(`Key expires in ${ttl}ms`);
+   * } else if (ttl === -2) {
+   *   console.log('Key has no expiration');
+   * } else {
+   *   console.log('Key does not exist');
+   * }
+   * ```
+   */
+  ttl(key: string): number;
+  /**
+   * Deletes a key-value pair
+   *
+   * @param key - The key to delete
+   *
+   * @example
+   * ```typescript
+   * kv.delete('user:123');
+   * ```
+   */
+  delete(key: string): void;
+  /**
+   * Checks if a key exists and is not expired
+   *
+   * @param key - The key to check
+   * @returns `true` if the key exists and is not expired, `false` otherwise
+   *
+   * @example
+   * ```typescript
+   * if (kv.has('user:123')) {
+   *   console.log('User exists and is not expired');
+   * }
+   * ```
+   */
+  has(key: string): boolean;
+  /**
+   * Gets all keys in the current namespace (excluding expired keys)
+   *
+   * @returns Array of all non-expired keys
+   *
+   * @example
+   * ```typescript
+   * const keys = kv.keys();
+   * console.log('All keys:', keys);
+   * ```
+   */
+  keys(): string[];
+  /**
+   * Gets all values in the current namespace (excluding expired keys)
+   *
+   * @returns Array of all non-expired values
+   *
+   * @example
+   * ```typescript
+   * const values = kv.values();
+   * console.log('All values:', values);
+   * ```
+   */
+  values(): string[];
+  /**
+   * Gets the total number of key-value pairs in the current namespace (excluding expired keys)
+   *
+   * @returns The count of non-expired key-value pairs
+   *
+   * @example
+   * ```typescript
+   * const count = kv.count();
+   * console.log(`Total entries: ${count}`);
+   * ```
+   */
+  count(): number;
+  /**
+   * Removes all key-value pairs from the current namespace
+   *
+   * @example
+   * ```typescript
+   * kv.clear(); // Removes all entries in current namespace
+   * ```
+   */
+  clear(): void;
+  /**
+   * Gets all key-value pairs as an object (excluding expired keys)
+   *
+   * @returns Object with all non-expired key-value pairs
+   *
+   * @example
+   * ```typescript
+   * const all = kv.all();
+   * console.log('All entries:', all);
+   * // Output: { 'key1': 'value1', 'key2': 'value2' }
+   * ```
+   */
+  all(): Record<string, string>;
+  /**
+   * Gets all available namespaces (tables) in the database
+   *
+   * @returns Array of namespace names
+   *
+   * @example
+   * ```typescript
+   * const namespaces = kv.namespaces();
+   * console.log('Available namespaces:', namespaces);
+   * ```
+   */
+  namespaces(): string[];
+  /**
+   * Gets the current namespace name
+   *
+   * @returns The current namespace string
+   */
+  getCurrentNamespace(): string;
+  /**
+   * Creates a new KV instance with a different namespace
+   *
+   * @param namespace - The namespace to use for the new instance
+   * @returns A new KV instance with the specified namespace
+   *
+   * @example
+   * ```typescript
+   * const userKv = kv.namespace('users');
+   * const configKv = kv.namespace('config');
+   *
+   * userKv.set('123', 'John Doe');
+   * configKv.set('theme', 'dark');
+   * ```
+   */
+  namespace(namespace: string): KV;
+  /**
+   * Iterator implementation for iterating over all non-expired key-value pairs
+   *
+   * @returns Iterator yielding [key, value] tuples
+   *
+   * @example
+   * ```typescript
+   * for (const [key, value] of kv) {
+   *   console.log(`${key}: ${value}`);
+   * }
+   *
+   * // Or using spread operator
+   * const entries = [...kv];
+   * ```
+   */
+  [Symbol.iterator](): Iterator<[string, string]>;
+  /**
+   * Executes a function within a transaction
+   *
+   * @param fn - Function to execute within the transaction (can be async)
+   * @returns The result of the function
+   *
+   * @example
+   * ```typescript
+   * // Synchronous transaction
+   * kv.transaction(() => {
+   *   kv.set('user:123', JSON.stringify({ name: 'John' }));
+   *   kv.set('user:456', JSON.stringify({ name: 'Jane' }));
+   *   // If any operation fails, all changes are rolled back
+   * });
+   *
+   * // Async transaction
+   * await kv.transaction(async () => {
+   *   kv.set('user:123', JSON.stringify({ name: 'John' }));
+   *   await someAsyncOperation();
+   *   kv.set('user:456', JSON.stringify({ name: 'Jane' }));
+   *   // If any operation fails, all changes are rolled back
+   * });
+   * ```
+   */
+  transaction<T>(fn: () => T | Promise<T>): Promise<T>;
+}
+/**
+ * Opens a new KV instance
+ *
+ * @param path - Database file path, buffer, URL, or existing DatabaseSync instance
+ * @param options - Configuration options for the KV store
+ * @returns A new KV instance
+ */
+declare function openKV(path?: string | Buffer | URL | DatabaseSync, options?: KvOptions): KV;
+//#endregion
+export { KV, KvOptions, openKV };
+//# sourceMappingURL=kv.d.ts.map