diff --git a/apps/website/docs/api-reference/commandkit/classes/kv.mdx b/apps/website/docs/api-reference/commandkit/classes/kv.mdx index a4d89d40..8b50c341 100644 --- a/apps/website/docs/api-reference/commandkit/classes/kv.mdx +++ b/apps/website/docs/api-reference/commandkit/classes/kv.mdx @@ -13,12 +13,12 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## KV - + 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. +with support for namespaces, automatic cleanup, iteration, expiration, and JSON serialization. @@ -26,12 +26,20 @@ with support for namespaces, automatic cleanup, iteration, and expiration. ```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' })); +// Store any JSON-serializable data +kv.set('user:123', { name: 'John', age: 30 }); +kv.set('counter', 42); +kv.set('active', true); +kv.set('dates', [new Date(), new Date()]); + +// Use dot notation for nested properties +kv.set('user:123.name', 'John'); +kv.set('user:123.settings.theme', 'dark'); + +// Retrieve data +const user = kv.get('user:123'); // { name: 'John', age: 30, settings: { theme: 'dark' } } +const name = kv.get('user:123.name'); // 'John' ``` ```ts title="Signature" @@ -45,22 +53,22 @@ class KV implements Disposable, AsyncDisposable { close() => void; [Symbol.dispose]() => ; [Symbol.asyncDispose]() => ; - get(key: string) => string | undefined; - set(key: string, value: string) => void; - setex(key: string, value: string, ttl: number) => void; + get(key: string) => T | undefined; + set(key: string, value: any) => void; + setex(key: string, value: any, ttl: number) => void; expire(key: string, ttl: number) => boolean; ttl(key: string) => number; delete(key: string) => void; has(key: string) => boolean; keys() => string[]; - values() => string[]; + values() => any[]; count() => number; clear() => void; - all() => Record; + all() => Record; namespaces() => string[]; getCurrentNamespace() => string; namespace(namespace: string) => KV; - [Symbol.iterator]() => Iterator<[string, string]>; + [Symbol.iterator]() => Iterator<[string, any]>; transaction(fn: () => T | Promise) => Promise; } ``` @@ -105,7 +113,7 @@ Disposable implementation - closes the database when disposed AsyncDisposable implementation - closes the database when disposed ### get - string | undefined`} /> + T | undefined`} /> Retrieves a value by key @@ -114,14 +122,20 @@ Retrieves a value by key *Example* ```typescript -const value = kv.get('my-key'); -if (value) { - console.log('Found:', value); -} +// Store an object +kv.set('user:123', { name: 'John', age: 30, settings: { theme: 'dark' } }); + +// Get the entire object +const user = kv.get('user:123'); +// { name: 'John', age: 30, settings: { theme: 'dark' } } + +// Get nested properties using dot notation +const name = kv.get('user:123.name'); // 'John' +const theme = kv.get('user:123.settings.theme'); // 'dark' ``` ### set - void`} /> + void`} /> Sets a key-value pair @@ -130,12 +144,31 @@ Sets a key-value pair *Example* ```typescript -kv.set('user:123', JSON.stringify({ name: 'John' })); -kv.set('counter', '42'); +// Store primitive values +kv.set('counter', 42); +kv.set('active', true); +kv.set('name', 'John'); + +// Store objects +kv.set('user:123', { name: 'John', age: 30 }); + +// Store arrays +kv.set('tags', ['javascript', 'typescript', 'sqlite']); + +// Store dates +kv.set('created', new Date()); + +// Store maps and sets +kv.set('permissions', new Map([['admin', true], ['user', false]])); +kv.set('unique_ids', new Set([1, 2, 3, 4, 5])); + +// Use dot notation for nested properties +kv.set('user:123.settings.theme', 'dark'); +kv.set('user:123.settings.notifications', true); ``` ### setex - void`} /> + void`} /> Sets a key-value pair with expiration @@ -145,10 +178,13 @@ Sets a key-value pair with expiration ```typescript // Set with 1 hour expiration -kv.setex('session:123', 'user_data', 60 * 60 * 1000); +kv.setex('session:123', { userId: 123, token: 'abc123' }, 60 * 60 * 1000); // Set with 5 minutes expiration -kv.setex('temp:data', 'cached_value', 5 * 60 * 1000); +kv.setex('temp:data', { cached: true, timestamp: Date.now() }, 5 * 60 * 1000); + +// Use dot notation with expiration +kv.setex('user:123.temp_settings', { theme: 'light' }, 30 * 60 * 1000); ``` ### expire @@ -161,7 +197,7 @@ Sets expiration for an existing key *Example* ```typescript -kv.set('user:123', 'user_data'); +kv.set('user:123', { name: 'John', age: 30 }); // Set 30 minute expiration if (kv.expire('user:123', 30 * 60 * 1000)) { @@ -200,6 +236,7 @@ Deletes a key-value pair ```typescript kv.delete('user:123'); +kv.delete('user:123.settings.theme'); // Delete nested property ``` ### has @@ -215,6 +252,10 @@ Checks if a key exists and is not expired if (kv.has('user:123')) { console.log('User exists and is not expired'); } + +if (kv.has('user:123.settings.theme')) { + console.log('Theme setting exists'); +} ``` ### keys @@ -232,7 +273,7 @@ console.log('All keys:', keys); ``` ### values - string[]`} /> + any[]`} /> Gets all values in the current namespace (excluding expired keys) @@ -273,7 +314,7 @@ kv.clear(); // Removes all entries in current namespace ``` ### all - Record<string, string>`} /> + Record<string, any>`} /> Gets all key-value pairs as an object (excluding expired keys) @@ -284,7 +325,7 @@ Gets all key-value pairs as an object (excluding expired keys) ```typescript const all = kv.all(); console.log('All entries:', all); -// Output: { 'key1': 'value1', 'key2': 'value2' } +// Output: { 'key1': value1, 'key2': value2 } ``` ### namespaces @@ -319,12 +360,12 @@ Creates a new KV instance with a different namespace const userKv = kv.namespace('users'); const configKv = kv.namespace('config'); -userKv.set('123', 'John Doe'); +userKv.set('123', { name: 'John', age: 30 }); configKv.set('theme', 'dark'); ``` ### \[Symbol.iterator] - Iterator<[string, string]>`} /> + Iterator<[string, any]>`} /> Iterator implementation for iterating over all non-expired key-value pairs @@ -334,7 +375,7 @@ Iterator implementation for iterating over all non-expired key-value pairs ```typescript for (const [key, value] of kv) { - console.log(`${key}: ${value}`); + console.log(`${key}:`, value); } // Or using spread operator @@ -353,16 +394,16 @@ Executes a function within a transaction ```typescript // Synchronous transaction kv.transaction(() => { - kv.set('user:123', JSON.stringify({ name: 'John' })); - kv.set('user:456', JSON.stringify({ name: 'Jane' })); + kv.set('user:123', { name: 'John', age: 30 }); + kv.set('user:456', { name: 'Jane', age: 25 }); // If any operation fails, all changes are rolled back }); // Async transaction await kv.transaction(async () => { - kv.set('user:123', JSON.stringify({ name: 'John' })); + kv.set('user:123', { name: 'John', age: 30 }); await someAsyncOperation(); - kv.set('user:456', JSON.stringify({ name: 'Jane' })); + kv.set('user:456', { name: 'Jane', age: 25 }); // If any operation fails, all changes are rolled back }); ``` diff --git a/apps/website/docs/api-reference/commandkit/enums/serializer-type.mdx b/apps/website/docs/api-reference/commandkit/enums/serializer-type.mdx new file mode 100644 index 00000000..9b47228f --- /dev/null +++ b/apps/website/docs/api-reference/commandkit/enums/serializer-type.mdx @@ -0,0 +1,36 @@ +--- +title: "SerializerType" +isDefaultIndex: false +generated: true +--- + +import MemberInfo from '@site/src/components/MemberInfo'; +import GenerationInfo from '@site/src/components/GenerationInfo'; +import MemberDescription from '@site/src/components/MemberDescription'; + + + + +## SerializerType + + + + + +```ts title="Signature" +enum SerializerType { + String + Number + Boolean + Object + Date + BigInt + Null + Undefined + Array + Map + Set + Buffer + RegExp +} +``` diff --git a/apps/website/docs/api-reference/commandkit/functions/deserializer.mdx b/apps/website/docs/api-reference/commandkit/functions/deserializer.mdx new file mode 100644 index 00000000..e6c9a3d5 --- /dev/null +++ b/apps/website/docs/api-reference/commandkit/functions/deserializer.mdx @@ -0,0 +1,28 @@ +--- +title: "Deserializer" +isDefaultIndex: false +generated: true +--- + +import MemberInfo from '@site/src/components/MemberInfo'; +import GenerationInfo from '@site/src/components/GenerationInfo'; +import MemberDescription from '@site/src/components/MemberDescription'; + + + + +## deserializer + + + + + +```ts title="Signature" +function deserializer(serialized: SerializedValue): any +``` +Parameters + +### serialized + +SerializedValue`} /> + diff --git a/apps/website/docs/api-reference/commandkit/functions/get-nested-value.mdx b/apps/website/docs/api-reference/commandkit/functions/get-nested-value.mdx new file mode 100644 index 00000000..06b2c0eb --- /dev/null +++ b/apps/website/docs/api-reference/commandkit/functions/get-nested-value.mdx @@ -0,0 +1,32 @@ +--- +title: "GetNestedValue" +isDefaultIndex: false +generated: true +--- + +import MemberInfo from '@site/src/components/MemberInfo'; +import GenerationInfo from '@site/src/components/GenerationInfo'; +import MemberDescription from '@site/src/components/MemberDescription'; + + + + +## getNestedValue + + + + + +```ts title="Signature" +function getNestedValue(obj: any, path: string): any +``` +Parameters + +### obj + + + +### path + + + diff --git a/apps/website/docs/api-reference/commandkit/functions/open-kv.mdx b/apps/website/docs/api-reference/commandkit/functions/open-kv.mdx index 42c2a940..45a7eb2c 100644 --- a/apps/website/docs/api-reference/commandkit/functions/open-kv.mdx +++ b/apps/website/docs/api-reference/commandkit/functions/open-kv.mdx @@ -13,7 +13,7 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## openKV - + Opens a new KV instance diff --git a/apps/website/docs/api-reference/commandkit/functions/serializer.mdx b/apps/website/docs/api-reference/commandkit/functions/serializer.mdx new file mode 100644 index 00000000..69308c34 --- /dev/null +++ b/apps/website/docs/api-reference/commandkit/functions/serializer.mdx @@ -0,0 +1,28 @@ +--- +title: "Serializer" +isDefaultIndex: false +generated: true +--- + +import MemberInfo from '@site/src/components/MemberInfo'; +import GenerationInfo from '@site/src/components/GenerationInfo'; +import MemberDescription from '@site/src/components/MemberDescription'; + + + + +## serializer + + + + + +```ts title="Signature" +function serializer(value: any): SerializedValue +``` +Parameters + +### value + + + diff --git a/apps/website/docs/api-reference/commandkit/functions/set-nested-value.mdx b/apps/website/docs/api-reference/commandkit/functions/set-nested-value.mdx new file mode 100644 index 00000000..56adfedc --- /dev/null +++ b/apps/website/docs/api-reference/commandkit/functions/set-nested-value.mdx @@ -0,0 +1,36 @@ +--- +title: "SetNestedValue" +isDefaultIndex: false +generated: true +--- + +import MemberInfo from '@site/src/components/MemberInfo'; +import GenerationInfo from '@site/src/components/GenerationInfo'; +import MemberDescription from '@site/src/components/MemberDescription'; + + + + +## setNestedValue + + + + + +```ts title="Signature" +function setNestedValue(obj: any, path: string, value: any): void +``` +Parameters + +### obj + + + +### path + + + +### value + + + diff --git a/apps/website/docs/api-reference/commandkit/interfaces/kv-options.mdx b/apps/website/docs/api-reference/commandkit/interfaces/kv-options.mdx index e89a56e2..babdad8f 100644 --- a/apps/website/docs/api-reference/commandkit/interfaces/kv-options.mdx +++ b/apps/website/docs/api-reference/commandkit/interfaces/kv-options.mdx @@ -13,7 +13,7 @@ import MemberDescription from '@site/src/components/MemberDescription'; ## KvOptions - + Configuration options for the KV store diff --git a/apps/website/docs/api-reference/commandkit/interfaces/serialized-value.mdx b/apps/website/docs/api-reference/commandkit/interfaces/serialized-value.mdx new file mode 100644 index 00000000..be9d0e6f --- /dev/null +++ b/apps/website/docs/api-reference/commandkit/interfaces/serialized-value.mdx @@ -0,0 +1,41 @@ +--- +title: "SerializedValue" +isDefaultIndex: false +generated: true +--- + +import MemberInfo from '@site/src/components/MemberInfo'; +import GenerationInfo from '@site/src/components/GenerationInfo'; +import MemberDescription from '@site/src/components/MemberDescription'; + + + + +## SerializedValue + + + + + +```ts title="Signature" +interface SerializedValue { + t: SerializerType; + v: any; +} +``` + +
+ +### t + +SerializerType`} /> + + +### v + + + + + + +