Skip to content

Commit 1efdbd8

Browse files
authored
Merge pull request #296 from underctrl-io/docs
docs: generate api docs
2 parents a90d632 + 7c0d029 commit 1efdbd8

File tree

9 files changed

+279
-37
lines changed

9 files changed

+279
-37
lines changed

apps/website/docs/api-reference/commandkit/classes/kv.mdx

Lines changed: 76 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -13,25 +13,33 @@ import MemberDescription from '@site/src/components/MemberDescription';
1313

1414
## KV
1515

16-
<GenerationInfo sourceFile="packages/commandkit/src/kv/kv.ts" sourceLine="30" packageName="commandkit" />
16+
<GenerationInfo sourceFile="packages/commandkit/src/kv/kv.ts" sourceLine="42" packageName="commandkit" />
1717

1818
A key-value store implementation using SQLite
1919

2020
This class provides a simple, persistent key-value storage solution
21-
with support for namespaces, automatic cleanup, iteration, and expiration.
21+
with support for namespaces, automatic cleanup, iteration, expiration, and JSON serialization.
2222

2323

2424

2525
*Example*
2626

2727
```typescript
2828
const kv = new KV('data.db');
29-
kv.set('user:123', JSON.stringify({ name: 'John', age: 30 }));
30-
const user = JSON.parse(kv.get('user:123') || '{}');
3129

32-
// Using namespaces
33-
const userKv = kv.namespace('users');
34-
userKv.set('123', JSON.stringify({ name: 'John' }));
30+
// Store any JSON-serializable data
31+
kv.set('user:123', { name: 'John', age: 30 });
32+
kv.set('counter', 42);
33+
kv.set('active', true);
34+
kv.set('dates', [new Date(), new Date()]);
35+
36+
// Use dot notation for nested properties
37+
kv.set('user:123.name', 'John');
38+
kv.set('user:123.settings.theme', 'dark');
39+
40+
// Retrieve data
41+
const user = kv.get('user:123'); // { name: 'John', age: 30, settings: { theme: 'dark' } }
42+
const name = kv.get('user:123.name'); // 'John'
3543
```
3644

3745
```ts title="Signature"
@@ -45,22 +53,22 @@ class KV implements Disposable, AsyncDisposable {
4553
close() => void;
4654
[Symbol.dispose]() => ;
4755
[Symbol.asyncDispose]() => ;
48-
get(key: string) => string | undefined;
49-
set(key: string, value: string) => void;
50-
setex(key: string, value: string, ttl: number) => void;
56+
get(key: string) => T | undefined;
57+
set(key: string, value: any) => void;
58+
setex(key: string, value: any, ttl: number) => void;
5159
expire(key: string, ttl: number) => boolean;
5260
ttl(key: string) => number;
5361
delete(key: string) => void;
5462
has(key: string) => boolean;
5563
keys() => string[];
56-
values() => string[];
64+
values() => any[];
5765
count() => number;
5866
clear() => void;
59-
all() => Record<string, string>;
67+
all() => Record<string, any>;
6068
namespaces() => string[];
6169
getCurrentNamespace() => string;
6270
namespace(namespace: string) => KV;
63-
[Symbol.iterator]() => Iterator<[string, string]>;
71+
[Symbol.iterator]() => Iterator<[string, any]>;
6472
transaction(fn: () => T | Promise<T>) => Promise<T>;
6573
}
6674
```
@@ -105,7 +113,7 @@ Disposable implementation - closes the database when disposed
105113
AsyncDisposable implementation - closes the database when disposed
106114
### get
107115

108-
<MemberInfo kind="method" type={`(key: string) => string | undefined`} />
116+
<MemberInfo kind="method" type={`(key: string) => T | undefined`} />
109117

110118
Retrieves a value by key
111119

@@ -114,14 +122,20 @@ Retrieves a value by key
114122
*Example*
115123

116124
```typescript
117-
const value = kv.get('my-key');
118-
if (value) {
119-
console.log('Found:', value);
120-
}
125+
// Store an object
126+
kv.set('user:123', { name: 'John', age: 30, settings: { theme: 'dark' } });
127+
128+
// Get the entire object
129+
const user = kv.get('user:123');
130+
// { name: 'John', age: 30, settings: { theme: 'dark' } }
131+
132+
// Get nested properties using dot notation
133+
const name = kv.get('user:123.name'); // 'John'
134+
const theme = kv.get('user:123.settings.theme'); // 'dark'
121135
```
122136
### set
123137

124-
<MemberInfo kind="method" type={`(key: string, value: string) => void`} />
138+
<MemberInfo kind="method" type={`(key: string, value: any) => void`} />
125139

126140
Sets a key-value pair
127141

@@ -130,12 +144,31 @@ Sets a key-value pair
130144
*Example*
131145

132146
```typescript
133-
kv.set('user:123', JSON.stringify({ name: 'John' }));
134-
kv.set('counter', '42');
147+
// Store primitive values
148+
kv.set('counter', 42);
149+
kv.set('active', true);
150+
kv.set('name', 'John');
151+
152+
// Store objects
153+
kv.set('user:123', { name: 'John', age: 30 });
154+
155+
// Store arrays
156+
kv.set('tags', ['javascript', 'typescript', 'sqlite']);
157+
158+
// Store dates
159+
kv.set('created', new Date());
160+
161+
// Store maps and sets
162+
kv.set('permissions', new Map([['admin', true], ['user', false]]));
163+
kv.set('unique_ids', new Set([1, 2, 3, 4, 5]));
164+
165+
// Use dot notation for nested properties
166+
kv.set('user:123.settings.theme', 'dark');
167+
kv.set('user:123.settings.notifications', true);
135168
```
136169
### setex
137170

138-
<MemberInfo kind="method" type={`(key: string, value: string, ttl: number) => void`} />
171+
<MemberInfo kind="method" type={`(key: string, value: any, ttl: number) => void`} />
139172

140173
Sets a key-value pair with expiration
141174

@@ -145,10 +178,13 @@ Sets a key-value pair with expiration
145178

146179
```typescript
147180
// Set with 1 hour expiration
148-
kv.setex('session:123', 'user_data', 60 * 60 * 1000);
181+
kv.setex('session:123', { userId: 123, token: 'abc123' }, 60 * 60 * 1000);
149182

150183
// Set with 5 minutes expiration
151-
kv.setex('temp:data', 'cached_value', 5 * 60 * 1000);
184+
kv.setex('temp:data', { cached: true, timestamp: Date.now() }, 5 * 60 * 1000);
185+
186+
// Use dot notation with expiration
187+
kv.setex('user:123.temp_settings', { theme: 'light' }, 30 * 60 * 1000);
152188
```
153189
### expire
154190

@@ -161,7 +197,7 @@ Sets expiration for an existing key
161197
*Example*
162198

163199
```typescript
164-
kv.set('user:123', 'user_data');
200+
kv.set('user:123', { name: 'John', age: 30 });
165201

166202
// Set 30 minute expiration
167203
if (kv.expire('user:123', 30 * 60 * 1000)) {
@@ -200,6 +236,7 @@ Deletes a key-value pair
200236

201237
```typescript
202238
kv.delete('user:123');
239+
kv.delete('user:123.settings.theme'); // Delete nested property
203240
```
204241
### has
205242

@@ -215,6 +252,10 @@ Checks if a key exists and is not expired
215252
if (kv.has('user:123')) {
216253
console.log('User exists and is not expired');
217254
}
255+
256+
if (kv.has('user:123.settings.theme')) {
257+
console.log('Theme setting exists');
258+
}
218259
```
219260
### keys
220261

@@ -232,7 +273,7 @@ console.log('All keys:', keys);
232273
```
233274
### values
234275

235-
<MemberInfo kind="method" type={`() => string[]`} />
276+
<MemberInfo kind="method" type={`() => any[]`} />
236277

237278
Gets all values in the current namespace (excluding expired keys)
238279

@@ -273,7 +314,7 @@ kv.clear(); // Removes all entries in current namespace
273314
```
274315
### all
275316

276-
<MemberInfo kind="method" type={`() => Record&#60;string, string&#62;`} />
317+
<MemberInfo kind="method" type={`() => Record&#60;string, any&#62;`} />
277318

278319
Gets all key-value pairs as an object (excluding expired keys)
279320

@@ -284,7 +325,7 @@ Gets all key-value pairs as an object (excluding expired keys)
284325
```typescript
285326
const all = kv.all();
286327
console.log('All entries:', all);
287-
// Output: { 'key1': 'value1', 'key2': 'value2' }
328+
// Output: { 'key1': value1, 'key2': value2 }
288329
```
289330
### namespaces
290331

@@ -319,12 +360,12 @@ Creates a new KV instance with a different namespace
319360
const userKv = kv.namespace('users');
320361
const configKv = kv.namespace('config');
321362

322-
userKv.set('123', 'John Doe');
363+
userKv.set('123', { name: 'John', age: 30 });
323364
configKv.set('theme', 'dark');
324365
```
325366
### \[Symbol.iterator]
326367

327-
<MemberInfo kind="method" type={`() => Iterator&#60;[string, string]&#62;`} />
368+
<MemberInfo kind="method" type={`() => Iterator&#60;[string, any]&#62;`} />
328369

329370
Iterator implementation for iterating over all non-expired key-value pairs
330371

@@ -334,7 +375,7 @@ Iterator implementation for iterating over all non-expired key-value pairs
334375

335376
```typescript
336377
for (const [key, value] of kv) {
337-
console.log(`${key}: ${value}`);
378+
console.log(`${key}:`, value);
338379
}
339380

340381
// Or using spread operator
@@ -353,16 +394,16 @@ Executes a function within a transaction
353394
```typescript
354395
// Synchronous transaction
355396
kv.transaction(() => {
356-
kv.set('user:123', JSON.stringify({ name: 'John' }));
357-
kv.set('user:456', JSON.stringify({ name: 'Jane' }));
397+
kv.set('user:123', { name: 'John', age: 30 });
398+
kv.set('user:456', { name: 'Jane', age: 25 });
358399
// If any operation fails, all changes are rolled back
359400
});
360401

361402
// Async transaction
362403
await kv.transaction(async () => {
363-
kv.set('user:123', JSON.stringify({ name: 'John' }));
404+
kv.set('user:123', { name: 'John', age: 30 });
364405
await someAsyncOperation();
365-
kv.set('user:456', JSON.stringify({ name: 'Jane' }));
406+
kv.set('user:456', { name: 'Jane', age: 25 });
366407
// If any operation fails, all changes are rolled back
367408
});
368409
```
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: "SerializerType"
3+
isDefaultIndex: false
4+
generated: true
5+
---
6+
7+
import MemberInfo from '@site/src/components/MemberInfo';
8+
import GenerationInfo from '@site/src/components/GenerationInfo';
9+
import MemberDescription from '@site/src/components/MemberDescription';
10+
11+
<!-- This file was generated from the CommandKit source. Do not modify. Instead, re-run the "docgen" script -->
12+
13+
14+
## SerializerType
15+
16+
<GenerationInfo sourceFile="packages/commandkit/src/kv/constants.ts" sourceLine="1" packageName="commandkit" />
17+
18+
19+
20+
```ts title="Signature"
21+
enum SerializerType {
22+
String
23+
Number
24+
Boolean
25+
Object
26+
Date
27+
BigInt
28+
Null
29+
Undefined
30+
Array
31+
Map
32+
Set
33+
Buffer
34+
RegExp
35+
}
36+
```
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: "Deserializer"
3+
isDefaultIndex: false
4+
generated: true
5+
---
6+
7+
import MemberInfo from '@site/src/components/MemberInfo';
8+
import GenerationInfo from '@site/src/components/GenerationInfo';
9+
import MemberDescription from '@site/src/components/MemberDescription';
10+
11+
<!-- This file was generated from the CommandKit source. Do not modify. Instead, re-run the "docgen" script -->
12+
13+
14+
## deserializer
15+
16+
<GenerationInfo sourceFile="packages/commandkit/src/kv/serde.ts" sourceLine="68" packageName="commandkit" />
17+
18+
19+
20+
```ts title="Signature"
21+
function deserializer(serialized: SerializedValue): any
22+
```
23+
Parameters
24+
25+
### serialized
26+
27+
<MemberInfo kind="parameter" type={`<a href='/docs/next/api-reference/commandkit/interfaces/serialized-value#serializedvalue'>SerializedValue</a>`} />
28+
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: "GetNestedValue"
3+
isDefaultIndex: false
4+
generated: true
5+
---
6+
7+
import MemberInfo from '@site/src/components/MemberInfo';
8+
import GenerationInfo from '@site/src/components/GenerationInfo';
9+
import MemberDescription from '@site/src/components/MemberDescription';
10+
11+
<!-- This file was generated from the CommandKit source. Do not modify. Instead, re-run the "docgen" script -->
12+
13+
14+
## getNestedValue
15+
16+
<GenerationInfo sourceFile="packages/commandkit/src/kv/dotprops.ts" sourceLine="1" packageName="commandkit" />
17+
18+
19+
20+
```ts title="Signature"
21+
function getNestedValue(obj: any, path: string): any
22+
```
23+
Parameters
24+
25+
### obj
26+
27+
<MemberInfo kind="parameter" type={`any`} />
28+
29+
### path
30+
31+
<MemberInfo kind="parameter" type={`string`} />
32+

apps/website/docs/api-reference/commandkit/functions/open-kv.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ import MemberDescription from '@site/src/components/MemberDescription';
1313

1414
## openKV
1515

16-
<GenerationInfo sourceFile="packages/commandkit/src/kv/kv.ts" sourceLine="542" packageName="commandkit" />
16+
<GenerationInfo sourceFile="packages/commandkit/src/kv/kv.ts" sourceLine="620" packageName="commandkit" />
1717

1818
Opens a new KV instance
1919

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: "Serializer"
3+
isDefaultIndex: false
4+
generated: true
5+
---
6+
7+
import MemberInfo from '@site/src/components/MemberInfo';
8+
import GenerationInfo from '@site/src/components/GenerationInfo';
9+
import MemberDescription from '@site/src/components/MemberDescription';
10+
11+
<!-- This file was generated from the CommandKit source. Do not modify. Instead, re-run the "docgen" script -->
12+
13+
14+
## serializer
15+
16+
<GenerationInfo sourceFile="packages/commandkit/src/kv/serde.ts" sourceLine="8" packageName="commandkit" />
17+
18+
19+
20+
```ts title="Signature"
21+
function serializer(value: any): SerializedValue
22+
```
23+
Parameters
24+
25+
### value
26+
27+
<MemberInfo kind="parameter" type={`any`} />
28+

0 commit comments

Comments
 (0)