@marianmeres/kv 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +52 -0
- package/dist/adapter/abstract.d.ts +76 -0
- package/dist/adapter/abstract.js +99 -0
- package/dist/adapter/deno-kv.d.ts +1 -0
- package/dist/adapter/deno-kv.js +2 -0
- package/dist/adapter/memory.d.ts +43 -0
- package/dist/adapter/memory.js +222 -0
- package/dist/adapter/postgres.d.ts +46 -0
- package/dist/adapter/postgres.js +279 -0
- package/dist/adapter/redis.d.ts +41 -0
- package/dist/adapter/redis.js +221 -0
- package/dist/kv.d.ts +20 -0
- package/dist/kv.js +15 -0
- package/dist/mod.d.ts +1 -0
- package/dist/mod.js +1 -0
- package/dist/utils/sleep.d.ts +28 -0
- package/dist/utils/sleep.js +34 -0
- package/package.json +25 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Marian Meres
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# @marianmeres/kv
|
|
2
|
+
|
|
3
|
+
Key-value storage abstraction layer with support of multiple backend adapters:
|
|
4
|
+
- redis
|
|
5
|
+
- postgresql
|
|
6
|
+
- memory
|
|
7
|
+
|
|
8
|
+
TODO: Deno KV adapter
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
```shell
|
|
13
|
+
deno add jsr:@marianmeres/kv
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
```shell
|
|
17
|
+
npm i @marianmeres/kv
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Usage
|
|
21
|
+
|
|
22
|
+
```typescript
|
|
23
|
+
import { createKVClient } from '@marianmeres/kv';
|
|
24
|
+
|
|
25
|
+
const client = createKVClient(
|
|
26
|
+
"my-app-namespace",
|
|
27
|
+
type: 'redis' | 'postgres' | 'memory' = 'memory',
|
|
28
|
+
db: ..., // redisClient (for redis) or pg.Pool/pg.Client (for postgres)...
|
|
29
|
+
options, // other options
|
|
30
|
+
);
|
|
31
|
+
|
|
32
|
+
//
|
|
33
|
+
await client.set('my:foo:key', { my: "value" })
|
|
34
|
+
await client.get('my:foo:key'); // { my: "value" }
|
|
35
|
+
await client.keys('my:*'); // ['my:foo:key']
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Api
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
client.set(key: string, value: any, options?): Promise<boolean>
|
|
42
|
+
client.get(key: string): Promise<any>
|
|
43
|
+
client.delete(key: string): Promise<boolean>
|
|
44
|
+
client.exists(key: string): Promise<boolean>
|
|
45
|
+
client.keys(pattern: string): Promise<string[]>
|
|
46
|
+
client.clear(pattern: string): Promise<number>
|
|
47
|
+
client.setMultiple(keyValuePairs: [string, any][], options?): Promise<any[]>
|
|
48
|
+
client.getMultiple(keys: string[]): Promise<Record<string, any>>
|
|
49
|
+
client.transaction(operations: Operation[]): Promise<any[]>
|
|
50
|
+
client.expire(key: string, ttl: number): Promise<boolean>
|
|
51
|
+
client.ttl(key: string): Promise<Date | null | false>
|
|
52
|
+
```
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import type { Logger } from "@marianmeres/clog";
|
|
2
|
+
export interface SetOptions extends Record<string, any> {
|
|
3
|
+
ttl: number;
|
|
4
|
+
}
|
|
5
|
+
export interface AdapterInfo {
|
|
6
|
+
type: string;
|
|
7
|
+
}
|
|
8
|
+
export interface AdapterAbstractOptions extends Record<string, any> {
|
|
9
|
+
defaultTtl: number;
|
|
10
|
+
logger?: Logger;
|
|
11
|
+
}
|
|
12
|
+
export interface Operation {
|
|
13
|
+
type: "set" | "get" | "delete";
|
|
14
|
+
key: string;
|
|
15
|
+
value?: any;
|
|
16
|
+
options?: Partial<SetOptions>;
|
|
17
|
+
}
|
|
18
|
+
/** Abstract adapter definition */
|
|
19
|
+
export declare abstract class AdapterAbstract {
|
|
20
|
+
/**
|
|
21
|
+
* "Namespace" is a instance **internal** key prefix. Internal means it acts as a low
|
|
22
|
+
* level namespace (similar to db schema), not something you consider when working
|
|
23
|
+
* with kv pairs
|
|
24
|
+
*/
|
|
25
|
+
readonly namespace: string;
|
|
26
|
+
protected _type: string;
|
|
27
|
+
readonly options: AdapterAbstractOptions;
|
|
28
|
+
protected _initialized: boolean;
|
|
29
|
+
constructor(
|
|
30
|
+
/**
|
|
31
|
+
* "Namespace" is a instance **internal** key prefix. Internal means it acts as a low
|
|
32
|
+
* level namespace (similar to db schema), not something you consider when working
|
|
33
|
+
* with kv pairs
|
|
34
|
+
*/
|
|
35
|
+
namespace?: string, options?: Partial<AdapterAbstractOptions>);
|
|
36
|
+
protected _assertInitialized(): void;
|
|
37
|
+
protected _assertValidNamespace(): void;
|
|
38
|
+
protected _withNs(key: string): string;
|
|
39
|
+
protected _withoutNs(key: string): string;
|
|
40
|
+
/** Will connect the client instance to underlying store (if applicable) */
|
|
41
|
+
abstract initialize(): Promise<void>;
|
|
42
|
+
/** Will disconnect the client instance from underlying store (if applicable) */
|
|
43
|
+
abstract destroy(hard?: boolean): Promise<void>;
|
|
44
|
+
/** Will set key-value pair to the underlying store with given options */
|
|
45
|
+
set(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
46
|
+
/** Will get the key from the underlying store */
|
|
47
|
+
get(key: string): Promise<any>;
|
|
48
|
+
/** Will delete the key from the underlying store */
|
|
49
|
+
delete(key: string): Promise<boolean>;
|
|
50
|
+
/** Will check if the key exists in the underlying store */
|
|
51
|
+
exists(key: string): Promise<boolean>;
|
|
52
|
+
/** Will list all existing keys in the underlying store matching given pattern.
|
|
53
|
+
* Recognizes redis-like star wildcard format. */
|
|
54
|
+
keys(pattern: string): Promise<string[]>;
|
|
55
|
+
/** Will clear all existing keys in the underlying store matching given pattern.
|
|
56
|
+
* Recognizes redis-like star wildcard format. */
|
|
57
|
+
clear(pattern: string): Promise<number>;
|
|
58
|
+
/** Will set multiple kv pairs in one batch */
|
|
59
|
+
setMultiple(keyValuePairs: [string, any][], options?: Partial<SetOptions>): Promise<any[]>;
|
|
60
|
+
/** Will get multiple keys in one batch */
|
|
61
|
+
getMultiple(keys: string[]): Promise<Record<string, any>>;
|
|
62
|
+
/** Will do multiple operations within one transaction (where applicable) */
|
|
63
|
+
transaction(operations: Operation[]): Promise<any[]>;
|
|
64
|
+
/** Will set the expiration ttl on the given key to given ttl value */
|
|
65
|
+
expire(key: string, ttl: number): Promise<boolean>;
|
|
66
|
+
/** Will get the expiration Date for given key */
|
|
67
|
+
ttl(key: string): Promise<Date | null | false>;
|
|
68
|
+
/** Will get info about the current adapter instance */
|
|
69
|
+
info(): AdapterInfo;
|
|
70
|
+
/** Will dump all data for debugging purposes only. Use with caution. Intended for
|
|
71
|
+
* tests only */
|
|
72
|
+
__debug_dump(): Promise<Record<string, {
|
|
73
|
+
value: any;
|
|
74
|
+
ttl: Date | null | false;
|
|
75
|
+
}>>;
|
|
76
|
+
}
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
function notImplemented() {
|
|
2
|
+
throw new Error("Not implemented");
|
|
3
|
+
}
|
|
4
|
+
/** Abstract adapter definition */
|
|
5
|
+
export class AdapterAbstract {
|
|
6
|
+
namespace;
|
|
7
|
+
_type = "abstract";
|
|
8
|
+
options = {
|
|
9
|
+
defaultTtl: 0, // no ttl by default
|
|
10
|
+
};
|
|
11
|
+
_initialized = false;
|
|
12
|
+
constructor(
|
|
13
|
+
/**
|
|
14
|
+
* "Namespace" is a instance **internal** key prefix. Internal means it acts as a low
|
|
15
|
+
* level namespace (similar to db schema), not something you consider when working
|
|
16
|
+
* with kv pairs
|
|
17
|
+
*/
|
|
18
|
+
namespace = "", options = {}) {
|
|
19
|
+
this.namespace = namespace;
|
|
20
|
+
this.options = { ...this.options, ...(options || {}) };
|
|
21
|
+
this._assertValidNamespace();
|
|
22
|
+
}
|
|
23
|
+
_assertInitialized() {
|
|
24
|
+
if (!this._initialized) {
|
|
25
|
+
throw new Error("Client does not appear to be initialized");
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
_assertValidNamespace() {
|
|
29
|
+
if (this.namespace && !this.namespace.endsWith(":")) {
|
|
30
|
+
throw new TypeError(`Namespace must be either empty, or must end with a colon ("${this.namespace}")`);
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
_withNs(key) {
|
|
34
|
+
return this.namespace + key;
|
|
35
|
+
}
|
|
36
|
+
_withoutNs(key) {
|
|
37
|
+
if (this.namespace)
|
|
38
|
+
key = key.slice(this.namespace.length);
|
|
39
|
+
return key;
|
|
40
|
+
}
|
|
41
|
+
/** Will set key-value pair to the underlying store with given options */
|
|
42
|
+
set(key, value, options) {
|
|
43
|
+
return notImplemented();
|
|
44
|
+
}
|
|
45
|
+
/** Will get the key from the underlying store */
|
|
46
|
+
get(key) {
|
|
47
|
+
return notImplemented();
|
|
48
|
+
}
|
|
49
|
+
/** Will delete the key from the underlying store */
|
|
50
|
+
delete(key) {
|
|
51
|
+
return notImplemented();
|
|
52
|
+
}
|
|
53
|
+
/** Will check if the key exists in the underlying store */
|
|
54
|
+
exists(key) {
|
|
55
|
+
return notImplemented();
|
|
56
|
+
}
|
|
57
|
+
/** Will list all existing keys in the underlying store matching given pattern.
|
|
58
|
+
* Recognizes redis-like star wildcard format. */
|
|
59
|
+
keys(pattern) {
|
|
60
|
+
return notImplemented();
|
|
61
|
+
}
|
|
62
|
+
/** Will clear all existing keys in the underlying store matching given pattern.
|
|
63
|
+
* Recognizes redis-like star wildcard format. */
|
|
64
|
+
clear(pattern) {
|
|
65
|
+
return notImplemented();
|
|
66
|
+
}
|
|
67
|
+
/** Will set multiple kv pairs in one batch */
|
|
68
|
+
setMultiple(keyValuePairs, options) {
|
|
69
|
+
return notImplemented();
|
|
70
|
+
}
|
|
71
|
+
/** Will get multiple keys in one batch */
|
|
72
|
+
getMultiple(keys) {
|
|
73
|
+
return notImplemented();
|
|
74
|
+
}
|
|
75
|
+
/** Will do multiple operations within one transaction (where applicable) */
|
|
76
|
+
transaction(operations) {
|
|
77
|
+
return notImplemented();
|
|
78
|
+
}
|
|
79
|
+
/** Will set the expiration ttl on the given key to given ttl value */
|
|
80
|
+
expire(key, ttl) {
|
|
81
|
+
return notImplemented();
|
|
82
|
+
}
|
|
83
|
+
/** Will get the expiration Date for given key */
|
|
84
|
+
ttl(key) {
|
|
85
|
+
return notImplemented();
|
|
86
|
+
}
|
|
87
|
+
/** Will get info about the current adapter instance */
|
|
88
|
+
info() {
|
|
89
|
+
return {
|
|
90
|
+
type: this._type,
|
|
91
|
+
// ... todo: list features
|
|
92
|
+
};
|
|
93
|
+
}
|
|
94
|
+
/** Will dump all data for debugging purposes only. Use with caution. Intended for
|
|
95
|
+
* tests only */
|
|
96
|
+
__debug_dump() {
|
|
97
|
+
return notImplemented();
|
|
98
|
+
}
|
|
99
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetOptions } from "./abstract.js";
|
|
2
|
+
export interface AdapterMemoryOptions extends AdapterAbstractOptions {
|
|
3
|
+
/** Set 0 to disable */
|
|
4
|
+
ttlCleanupIntervalSec: number;
|
|
5
|
+
}
|
|
6
|
+
export declare class AdapterMemory extends AdapterAbstract {
|
|
7
|
+
#private;
|
|
8
|
+
readonly namespace: string;
|
|
9
|
+
_type: string;
|
|
10
|
+
readonly options: AdapterMemoryOptions;
|
|
11
|
+
constructor(namespace?: string, options?: Partial<AdapterMemoryOptions>);
|
|
12
|
+
/** Will initialize the client instance */
|
|
13
|
+
initialize(): Promise<void>;
|
|
14
|
+
/** Will destroy (do cleanups) on the instance */
|
|
15
|
+
destroy(_hard?: boolean): Promise<void>;
|
|
16
|
+
/** Will set key-value pair to the underlying store with given options */
|
|
17
|
+
set(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
18
|
+
/** Will get the key from the underlying store */
|
|
19
|
+
get(key: string): Promise<any>;
|
|
20
|
+
/** Will delete the key from the underlying store */
|
|
21
|
+
delete(key: string): Promise<boolean>;
|
|
22
|
+
/** Will check if the key exists in the underlying store */
|
|
23
|
+
exists(key: string): Promise<boolean>;
|
|
24
|
+
/** Will list all existing keys in the underlying store matching given pattern.
|
|
25
|
+
* Recognizes redis-like star wildcard format. */
|
|
26
|
+
keys(pattern: string): Promise<string[]>;
|
|
27
|
+
/** Will clear all existing keys in the underlying store matching given pattern */
|
|
28
|
+
clear(pattern: string): Promise<number>;
|
|
29
|
+
/** Will set multiple kv pairs in one batch */
|
|
30
|
+
setMultiple(keyValuePairs: [string, any][], options?: Partial<SetOptions>): Promise<boolean[]>;
|
|
31
|
+
/** Will get multiple keys in one batch */
|
|
32
|
+
getMultiple(keys: string[]): Promise<Record<string, any>>;
|
|
33
|
+
/** Will set the expiration ttl on the given key to given ttl value */
|
|
34
|
+
expire(key: string, ttl: number): Promise<boolean>;
|
|
35
|
+
/** Will get the expiration Date for given key */
|
|
36
|
+
ttl(key: string): Promise<Date | null | false>;
|
|
37
|
+
/** */
|
|
38
|
+
transaction(operations: Operation[]): Promise<any[]>;
|
|
39
|
+
__debug_dump(): Promise<Record<string, {
|
|
40
|
+
value: any;
|
|
41
|
+
ttl: Date | null | false;
|
|
42
|
+
}>>;
|
|
43
|
+
}
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
import { createLogger } from "@marianmeres/clog";
|
|
2
|
+
import { AdapterAbstract, } from "./abstract.js";
|
|
3
|
+
export class AdapterMemory extends AdapterAbstract {
|
|
4
|
+
namespace;
|
|
5
|
+
_type = "memory";
|
|
6
|
+
options = {
|
|
7
|
+
defaultTtl: 0, // no ttl by default
|
|
8
|
+
ttlCleanupIntervalSec: 0,
|
|
9
|
+
logger: createLogger("KV/memory"),
|
|
10
|
+
};
|
|
11
|
+
#store = new Map();
|
|
12
|
+
#expirations = new Map();
|
|
13
|
+
#cleanupTimer;
|
|
14
|
+
constructor(namespace = "", options = {}) {
|
|
15
|
+
super();
|
|
16
|
+
this.namespace = namespace;
|
|
17
|
+
this.options = { ...this.options, ...(options || {}) };
|
|
18
|
+
this._assertValidNamespace();
|
|
19
|
+
}
|
|
20
|
+
/** Will initialize the client instance */
|
|
21
|
+
initialize() {
|
|
22
|
+
this._initialized = true;
|
|
23
|
+
this.#maybeTTLCleanup();
|
|
24
|
+
return Promise.resolve(); // memory is always "connected"
|
|
25
|
+
}
|
|
26
|
+
/** Will destroy (do cleanups) on the instance */
|
|
27
|
+
destroy(_hard) {
|
|
28
|
+
this._initialized = false;
|
|
29
|
+
clearTimeout(this.#cleanupTimer);
|
|
30
|
+
return Promise.resolve();
|
|
31
|
+
}
|
|
32
|
+
#maybeTTLCleanup() {
|
|
33
|
+
clearTimeout(this.#cleanupTimer); // safety
|
|
34
|
+
if (this.options.ttlCleanupIntervalSec) {
|
|
35
|
+
// do the cleanup now
|
|
36
|
+
const now = new Date();
|
|
37
|
+
for (const [key, expiresAt] of this.#expirations.entries()) {
|
|
38
|
+
if (expiresAt.valueOf() <= now.valueOf()) {
|
|
39
|
+
this.#store.delete(key);
|
|
40
|
+
this.#expirations.delete(key);
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
// schedule next...
|
|
44
|
+
this.#cleanupTimer = setTimeout(this.#maybeTTLCleanup.bind(this), this.options.ttlCleanupIntervalSec * 1000);
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
#isExpired(key) {
|
|
48
|
+
const expiresAt = this.#expirations.get(key);
|
|
49
|
+
if (!expiresAt)
|
|
50
|
+
return false;
|
|
51
|
+
if (Date.now() > expiresAt.valueOf()) {
|
|
52
|
+
this.#store.delete(key);
|
|
53
|
+
this.#expirations.delete(key);
|
|
54
|
+
return true;
|
|
55
|
+
}
|
|
56
|
+
return false;
|
|
57
|
+
}
|
|
58
|
+
/** Will set key-value pair to the underlying store with given options */
|
|
59
|
+
set(key, value, options = {}) {
|
|
60
|
+
this._assertInitialized();
|
|
61
|
+
key = this._withNs(key);
|
|
62
|
+
// to be consistent across adapters, keeping internally the strigified version...
|
|
63
|
+
this.#store.set(key, JSON.stringify(value));
|
|
64
|
+
const ttl = options.ttl || this.options.defaultTtl;
|
|
65
|
+
if (ttl) {
|
|
66
|
+
this.#expirations.set(key, new Date(Date.now() + ttl * 1_000));
|
|
67
|
+
}
|
|
68
|
+
else {
|
|
69
|
+
this.#expirations.delete(key);
|
|
70
|
+
}
|
|
71
|
+
return Promise.resolve(true);
|
|
72
|
+
}
|
|
73
|
+
/** Will get the key from the underlying store */
|
|
74
|
+
get(key) {
|
|
75
|
+
this._assertInitialized();
|
|
76
|
+
key = this._withNs(key);
|
|
77
|
+
if (this.#isExpired(key))
|
|
78
|
+
return Promise.resolve(null);
|
|
79
|
+
const value = this.#store.get(key);
|
|
80
|
+
// NOTE: even if the saved value was `undefined` it is always returned as `null`
|
|
81
|
+
if (value === undefined)
|
|
82
|
+
return Promise.resolve(null);
|
|
83
|
+
return JSON.parse(value);
|
|
84
|
+
}
|
|
85
|
+
/** Will delete the key from the underlying store */
|
|
86
|
+
delete(key) {
|
|
87
|
+
this._assertInitialized();
|
|
88
|
+
key = this._withNs(key);
|
|
89
|
+
const existed = this.#store.has(key);
|
|
90
|
+
this.#store.delete(key);
|
|
91
|
+
this.#expirations.delete(key);
|
|
92
|
+
return Promise.resolve(existed);
|
|
93
|
+
}
|
|
94
|
+
/** Will check if the key exists in the underlying store */
|
|
95
|
+
exists(key) {
|
|
96
|
+
this._assertInitialized();
|
|
97
|
+
key = this._withNs(key);
|
|
98
|
+
if (this.#isExpired(key))
|
|
99
|
+
return Promise.resolve(false);
|
|
100
|
+
return Promise.resolve(this.#store.has(key));
|
|
101
|
+
}
|
|
102
|
+
/** Will list all existing keys in the underlying store matching given pattern.
|
|
103
|
+
* Recognizes redis-like star wildcard format. */
|
|
104
|
+
keys(pattern) {
|
|
105
|
+
this._assertInitialized();
|
|
106
|
+
const all = Array.from(this.#store.keys())
|
|
107
|
+
.filter((key) => !this.#isExpired(key))
|
|
108
|
+
.map((k) => {
|
|
109
|
+
// strip namespace if exists
|
|
110
|
+
if (this.namespace)
|
|
111
|
+
k = k.slice(this.namespace.length);
|
|
112
|
+
return k;
|
|
113
|
+
})
|
|
114
|
+
.toSorted();
|
|
115
|
+
if (pattern === "*")
|
|
116
|
+
return Promise.resolve(all);
|
|
117
|
+
// convert Redis-style pattern to regex
|
|
118
|
+
const regexPattern = pattern.replace(/\*/g, ".*").replace(/\?/g, ".");
|
|
119
|
+
const regex = new RegExp(`^${regexPattern}$`);
|
|
120
|
+
return Promise.resolve(all.filter((key) => regex.test(key)));
|
|
121
|
+
}
|
|
122
|
+
/** Will clear all existing keys in the underlying store matching given pattern */
|
|
123
|
+
async clear(pattern) {
|
|
124
|
+
this._assertInitialized();
|
|
125
|
+
const keysToDelete = await this.keys(pattern);
|
|
126
|
+
let deleteCount = 0;
|
|
127
|
+
for (let key of keysToDelete) {
|
|
128
|
+
key = this._withNs(key);
|
|
129
|
+
this.#store.delete(key);
|
|
130
|
+
this.#expirations.delete(key);
|
|
131
|
+
deleteCount++;
|
|
132
|
+
}
|
|
133
|
+
return deleteCount;
|
|
134
|
+
}
|
|
135
|
+
/** Will set multiple kv pairs in one batch */
|
|
136
|
+
async setMultiple(keyValuePairs, options = {}) {
|
|
137
|
+
this._assertInitialized();
|
|
138
|
+
const results = [];
|
|
139
|
+
for (const [key, value] of keyValuePairs) {
|
|
140
|
+
await this.set(key, value, options);
|
|
141
|
+
results.push(true);
|
|
142
|
+
}
|
|
143
|
+
return results;
|
|
144
|
+
}
|
|
145
|
+
/** Will get multiple keys in one batch */
|
|
146
|
+
async getMultiple(keys) {
|
|
147
|
+
this._assertInitialized();
|
|
148
|
+
const result = {};
|
|
149
|
+
for (const key of keys) {
|
|
150
|
+
result[key] = await this.get(key);
|
|
151
|
+
}
|
|
152
|
+
return result;
|
|
153
|
+
}
|
|
154
|
+
/** Will set the expiration ttl on the given key to given ttl value */
|
|
155
|
+
expire(key, ttl) {
|
|
156
|
+
this._assertInitialized();
|
|
157
|
+
key = this._withNs(key);
|
|
158
|
+
if (!this.#store.has(key) || this.#isExpired(key)) {
|
|
159
|
+
return Promise.resolve(false);
|
|
160
|
+
}
|
|
161
|
+
this.#expirations.set(key, new Date(Date.now() + ttl * 1000));
|
|
162
|
+
return Promise.resolve(true);
|
|
163
|
+
}
|
|
164
|
+
/** Will get the expiration Date for given key */
|
|
165
|
+
ttl(key) {
|
|
166
|
+
this._assertInitialized();
|
|
167
|
+
key = this._withNs(key);
|
|
168
|
+
// Key doesn't exist
|
|
169
|
+
if (!this.#store.has(key))
|
|
170
|
+
return Promise.resolve(false);
|
|
171
|
+
// Key expired (and was cleaned up)
|
|
172
|
+
if (this.#isExpired(key))
|
|
173
|
+
return Promise.resolve(false);
|
|
174
|
+
const expiresAt = this.#expirations.get(key);
|
|
175
|
+
// No expiration set
|
|
176
|
+
if (!expiresAt)
|
|
177
|
+
return Promise.resolve(null);
|
|
178
|
+
return Promise.resolve(expiresAt);
|
|
179
|
+
// const remaining = Math.max(0, expiresAt.valueOf() - Date.now());
|
|
180
|
+
// return Promise.resolve(new Date(Date.now() + Math.ceil(remaining)));
|
|
181
|
+
}
|
|
182
|
+
/** */
|
|
183
|
+
async transaction(operations) {
|
|
184
|
+
this._assertInitialized();
|
|
185
|
+
// note: memory operations are atomic by nature
|
|
186
|
+
const results = [];
|
|
187
|
+
try {
|
|
188
|
+
for (const op of operations) {
|
|
189
|
+
switch (op.type) {
|
|
190
|
+
case "set":
|
|
191
|
+
results.push(await this.set(op.key, op.value, op.options || {}));
|
|
192
|
+
break;
|
|
193
|
+
case "get":
|
|
194
|
+
results.push(await this.get(op.key));
|
|
195
|
+
break;
|
|
196
|
+
case "delete":
|
|
197
|
+
results.push(await this.delete(op.key));
|
|
198
|
+
break;
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
catch (err) {
|
|
203
|
+
// rollback here in a real db-based adapter
|
|
204
|
+
throw err;
|
|
205
|
+
}
|
|
206
|
+
return results;
|
|
207
|
+
}
|
|
208
|
+
async __debug_dump() {
|
|
209
|
+
this._assertInitialized();
|
|
210
|
+
const out = {};
|
|
211
|
+
for (let k of this.#store.keys()) {
|
|
212
|
+
// need to strip the namespace from the key
|
|
213
|
+
if (this.namespace)
|
|
214
|
+
k = k.slice(this.namespace.length);
|
|
215
|
+
out[k] = {
|
|
216
|
+
value: await this.get(k),
|
|
217
|
+
ttl: await this.ttl(k),
|
|
218
|
+
};
|
|
219
|
+
}
|
|
220
|
+
return Promise.resolve(out);
|
|
221
|
+
}
|
|
222
|
+
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { AdapterAbstract, type Operation, type SetOptions, type AdapterAbstractOptions } from "./abstract.js";
|
|
2
|
+
import type pg from "pg";
|
|
3
|
+
export interface AdapterPostgresOptions extends AdapterAbstractOptions {
|
|
4
|
+
/** pg.Pool or pg.Client instance */
|
|
5
|
+
db: pg.Pool | pg.Client;
|
|
6
|
+
/** */
|
|
7
|
+
tableName: string;
|
|
8
|
+
/** Set 0 to disable */
|
|
9
|
+
ttlCleanupIntervalSec: number;
|
|
10
|
+
}
|
|
11
|
+
export declare class AdapterPostgres extends AdapterAbstract {
|
|
12
|
+
#private;
|
|
13
|
+
readonly namespace: string;
|
|
14
|
+
_type: string;
|
|
15
|
+
readonly options: AdapterPostgresOptions;
|
|
16
|
+
constructor(namespace?: string, options?: Partial<AdapterPostgresOptions>);
|
|
17
|
+
initialize(): Promise<void>;
|
|
18
|
+
destroy(hard?: boolean): Promise<void>;
|
|
19
|
+
/** Will set key-value pair to the underlying store with given options */
|
|
20
|
+
set(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
21
|
+
/** Will get the key from the underlying store */
|
|
22
|
+
get(key: string): Promise<any>;
|
|
23
|
+
/** Will delete the key from the underlying store */
|
|
24
|
+
delete(key: string): Promise<boolean>;
|
|
25
|
+
/** Will check if the key exists in the underlying store */
|
|
26
|
+
exists(key: string): Promise<boolean>;
|
|
27
|
+
/** Will list all existing keys in the underlying store matching given pattern.
|
|
28
|
+
* Recognizes redis-like star wildcard format. */
|
|
29
|
+
keys(pattern: string): Promise<string[]>;
|
|
30
|
+
/** Will clear all existing keys in the underlying store matching given pattern */
|
|
31
|
+
clear(pattern: string): Promise<number>;
|
|
32
|
+
/** Will set multiple kv pairs in one batch */
|
|
33
|
+
setMultiple(keyValuePairs: [string, any][], options?: Partial<SetOptions>): Promise<boolean[]>;
|
|
34
|
+
/** Will get multiple keys in one batch */
|
|
35
|
+
getMultiple(keys: string[]): Promise<Record<string, any>>;
|
|
36
|
+
/** Will set the expiration ttl on the given key to given ttl value */
|
|
37
|
+
expire(key: string, ttl: number): Promise<boolean>;
|
|
38
|
+
/** Will get the expiration Date for given key */
|
|
39
|
+
ttl(key: string): Promise<Date | null | false>;
|
|
40
|
+
/** */
|
|
41
|
+
transaction(operations: Operation[]): Promise<any[]>;
|
|
42
|
+
__debug_dump(): Promise<Record<string, {
|
|
43
|
+
value: any;
|
|
44
|
+
ttl: Date | null | false;
|
|
45
|
+
}>>;
|
|
46
|
+
}
|
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
import { AdapterAbstract, } from "./abstract.js";
|
|
2
|
+
import { createLogger } from "@marianmeres/clog";
|
|
3
|
+
export class AdapterPostgres extends AdapterAbstract {
|
|
4
|
+
namespace;
|
|
5
|
+
_type = "postgres";
|
|
6
|
+
options = {
|
|
7
|
+
defaultTtl: 0, // no ttl by default
|
|
8
|
+
logger: createLogger("KV/memory"),
|
|
9
|
+
db: null,
|
|
10
|
+
tableName: "__kv",
|
|
11
|
+
ttlCleanupIntervalSec: 0,
|
|
12
|
+
};
|
|
13
|
+
#cleanupTimer;
|
|
14
|
+
constructor(namespace = "", options = {}) {
|
|
15
|
+
super();
|
|
16
|
+
this.namespace = namespace;
|
|
17
|
+
this._assertValidNamespace();
|
|
18
|
+
this.options = { ...this.options, ...(options || {}) };
|
|
19
|
+
if (!this.options.db) {
|
|
20
|
+
throw new Error("Missing pg instance");
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
async initialize() {
|
|
24
|
+
const { db, tableName } = this.options;
|
|
25
|
+
// so we can work with "schema." prefix in naming things...
|
|
26
|
+
const safe = (name) => `${name}`.replace(/\W/g, "");
|
|
27
|
+
await db.query(`
|
|
28
|
+
CREATE TABLE IF NOT EXISTS ${tableName} (
|
|
29
|
+
key VARCHAR(255) PRIMARY KEY,
|
|
30
|
+
value JSONB NOT NULL,
|
|
31
|
+
expires_at TIMESTAMP WITH TIME ZONE,
|
|
32
|
+
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
|
33
|
+
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
|
|
34
|
+
)
|
|
35
|
+
`);
|
|
36
|
+
await db.query(`
|
|
37
|
+
CREATE INDEX IF NOT EXISTS idx_${safe(tableName)}_expires_at
|
|
38
|
+
ON ${tableName} (expires_at)
|
|
39
|
+
WHERE expires_at IS NOT NULL
|
|
40
|
+
`);
|
|
41
|
+
this._initialized = true;
|
|
42
|
+
this.#maybeTTLCleanup();
|
|
43
|
+
}
|
|
44
|
+
async destroy(hard) {
|
|
45
|
+
if (hard) {
|
|
46
|
+
const { db, tableName } = this.options;
|
|
47
|
+
await db.query(`DROP TABLE IF EXISTS ${tableName}`);
|
|
48
|
+
}
|
|
49
|
+
this._initialized = false;
|
|
50
|
+
clearTimeout(this.#cleanupTimer);
|
|
51
|
+
}
|
|
52
|
+
async #maybeTTLCleanup() {
|
|
53
|
+
clearTimeout(this.#cleanupTimer); // safety
|
|
54
|
+
if (this.options.ttlCleanupIntervalSec) {
|
|
55
|
+
const { db, tableName, logger } = this.options;
|
|
56
|
+
// do the cleanup now
|
|
57
|
+
try {
|
|
58
|
+
await db.query(`
|
|
59
|
+
DELETE FROM ${tableName}
|
|
60
|
+
WHERE expires_at IS NOT NULL AND expires_at <= NOW()`);
|
|
61
|
+
}
|
|
62
|
+
catch (err) {
|
|
63
|
+
logger?.error?.(`TTL cleanup error: ${err}`);
|
|
64
|
+
}
|
|
65
|
+
// schedule next...
|
|
66
|
+
this.#cleanupTimer = setTimeout(this.#maybeTTLCleanup.bind(this), this.options.ttlCleanupIntervalSec * 1000);
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
/** convert Redis-style pattern to PostgreSQL LIKE pattern */
|
|
70
|
+
#likePattern(pattern) {
|
|
71
|
+
return pattern.replace(/\*/g, "%").replace(/\?/g, "_");
|
|
72
|
+
}
|
|
73
|
+
/** Will set key-value pair to the underlying store with given options */
|
|
74
|
+
async set(key, value, options = {}) {
|
|
75
|
+
this._assertInitialized();
|
|
76
|
+
key = this._withNs(key);
|
|
77
|
+
const { db, tableName } = this.options;
|
|
78
|
+
const ttl = options.ttl || this.options.defaultTtl;
|
|
79
|
+
const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
|
|
80
|
+
// a.k.a. UPSERT
|
|
81
|
+
await db.query(`INSERT INTO ${tableName} (key, value, expires_at, updated_at)
|
|
82
|
+
VALUES ($1, $2, $3, NOW())
|
|
83
|
+
ON CONFLICT (key) DO UPDATE SET
|
|
84
|
+
value = EXCLUDED.value,
|
|
85
|
+
expires_at = EXCLUDED.expires_at,
|
|
86
|
+
updated_at = NOW()`, [key, JSON.stringify(value ?? null), expiresAt]);
|
|
87
|
+
return true;
|
|
88
|
+
}
|
|
89
|
+
/** Will get the key from the underlying store */
|
|
90
|
+
async get(key) {
|
|
91
|
+
this._assertInitialized();
|
|
92
|
+
key = this._withNs(key);
|
|
93
|
+
const { db, tableName } = this.options;
|
|
94
|
+
const { rows } = await db.query(`SELECT value, expires_at
|
|
95
|
+
FROM ${tableName}
|
|
96
|
+
WHERE key = $1 AND (expires_at IS NULL OR expires_at > NOW())`, [key]);
|
|
97
|
+
if (rows.length === 0)
|
|
98
|
+
return null;
|
|
99
|
+
return rows[0].value;
|
|
100
|
+
}
|
|
101
|
+
/** Will delete the key from the underlying store */
|
|
102
|
+
async delete(key) {
|
|
103
|
+
this._assertInitialized();
|
|
104
|
+
key = this._withNs(key);
|
|
105
|
+
const { db, tableName } = this.options;
|
|
106
|
+
const { rowCount } = await db.query(`DELETE FROM ${tableName} WHERE key = $1`, [key]);
|
|
107
|
+
return rowCount > 0;
|
|
108
|
+
}
|
|
109
|
+
/** Will check if the key exists in the underlying store */
|
|
110
|
+
async exists(key) {
|
|
111
|
+
this._assertInitialized();
|
|
112
|
+
key = this._withNs(key);
|
|
113
|
+
const { db, tableName } = this.options;
|
|
114
|
+
const { rows } = await db.query(`SELECT 1 FROM ${tableName}
|
|
115
|
+
WHERE key = $1 AND (expires_at IS NULL OR expires_at > NOW())`, [key]);
|
|
116
|
+
return rows.length > 0;
|
|
117
|
+
}
|
|
118
|
+
/** Will list all existing keys in the underlying store matching given pattern.
|
|
119
|
+
* Recognizes redis-like star wildcard format. */
|
|
120
|
+
async keys(pattern) {
|
|
121
|
+
this._assertInitialized();
|
|
122
|
+
const { db, tableName } = this.options;
|
|
123
|
+
let params = [];
|
|
124
|
+
const query = `
|
|
125
|
+
SELECT key FROM ${tableName}
|
|
126
|
+
WHERE key LIKE $1
|
|
127
|
+
AND (expires_at IS NULL OR expires_at > NOW())
|
|
128
|
+
ORDER BY key`;
|
|
129
|
+
if (pattern === "*") {
|
|
130
|
+
params = [this.namespace + "%"];
|
|
131
|
+
}
|
|
132
|
+
else {
|
|
133
|
+
params = [this.namespace + this.#likePattern(pattern)];
|
|
134
|
+
}
|
|
135
|
+
const { rows } = await db.query(query, params);
|
|
136
|
+
return rows
|
|
137
|
+
.map((row) => {
|
|
138
|
+
let k = row.key;
|
|
139
|
+
// strip namespace if exists
|
|
140
|
+
if (this.namespace)
|
|
141
|
+
k = k.slice(this.namespace.length);
|
|
142
|
+
return k;
|
|
143
|
+
})
|
|
144
|
+
.toSorted();
|
|
145
|
+
}
|
|
146
|
+
/** Will clear all existing keys in the underlying store matching given pattern */
|
|
147
|
+
async clear(pattern) {
|
|
148
|
+
this._assertInitialized();
|
|
149
|
+
const { db, tableName } = this.options;
|
|
150
|
+
let params = [];
|
|
151
|
+
const query = `DELETE FROM ${tableName} WHERE key LIKE $1`;
|
|
152
|
+
if (pattern === "*") {
|
|
153
|
+
params = [this.namespace + "%"];
|
|
154
|
+
}
|
|
155
|
+
else {
|
|
156
|
+
params = [this.namespace + this.#likePattern(pattern)];
|
|
157
|
+
}
|
|
158
|
+
const { rowCount } = await db.query(query, params);
|
|
159
|
+
return rowCount;
|
|
160
|
+
}
|
|
161
|
+
/** Will set multiple kv pairs in one batch */
|
|
162
|
+
async setMultiple(keyValuePairs, options = {}) {
|
|
163
|
+
this._assertInitialized();
|
|
164
|
+
const { db, tableName } = this.options;
|
|
165
|
+
const ttl = options.ttl || this.options.defaultTtl;
|
|
166
|
+
const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
|
|
167
|
+
const values = Object.entries(keyValuePairs)
|
|
168
|
+
.map(([_k, _v], i) => `($${i * 3 + 1}, $${i * 3 + 2}, $${i * 3 + 3})`)
|
|
169
|
+
.join(", ");
|
|
170
|
+
const params = keyValuePairs.reduce((m, [k, v]) => [...m, this._withNs(k), JSON.stringify(v), expiresAt], []);
|
|
171
|
+
// a.k.a UPSERT
|
|
172
|
+
const sql = `
|
|
173
|
+
INSERT INTO ${tableName} (key, value, expires_at)
|
|
174
|
+
VALUES ${values}
|
|
175
|
+
ON CONFLICT (key) DO UPDATE SET
|
|
176
|
+
value = EXCLUDED.value,
|
|
177
|
+
expires_at = EXCLUDED.expires_at,
|
|
178
|
+
updated_at = NOW()
|
|
179
|
+
`;
|
|
180
|
+
// console.log(sql, params);
|
|
181
|
+
await db.query(sql, params);
|
|
182
|
+
return keyValuePairs.map(() => true);
|
|
183
|
+
}
|
|
184
|
+
/** Will get multiple keys in one batch */
|
|
185
|
+
async getMultiple(keys) {
|
|
186
|
+
this._assertInitialized();
|
|
187
|
+
if (keys.length === 0)
|
|
188
|
+
return {};
|
|
189
|
+
const placeholders = keys.map((_, i) => `$${i + 1}`).join(", ");
|
|
190
|
+
const { db, tableName } = this.options;
|
|
191
|
+
const sql = `
|
|
192
|
+
SELECT key, value
|
|
193
|
+
FROM ${tableName}
|
|
194
|
+
WHERE key IN (${placeholders}) AND (expires_at IS NULL OR expires_at > NOW())
|
|
195
|
+
`;
|
|
196
|
+
const params = keys.map((k) => this._withNs(k));
|
|
197
|
+
// console.log(sql, params);
|
|
198
|
+
const { rows } = await db.query(sql, params);
|
|
199
|
+
const found = {};
|
|
200
|
+
rows.forEach((row) => {
|
|
201
|
+
const key = this._withoutNs(row.key);
|
|
202
|
+
found[key] = row.value;
|
|
203
|
+
});
|
|
204
|
+
// ensure all requested keys are in the result
|
|
205
|
+
const resultMap = {};
|
|
206
|
+
keys.forEach((key) => {
|
|
207
|
+
resultMap[key] = found[key] || null;
|
|
208
|
+
});
|
|
209
|
+
return resultMap;
|
|
210
|
+
}
|
|
211
|
+
/** Will set the expiration ttl on the given key to given ttl value */
|
|
212
|
+
async expire(key, ttl) {
|
|
213
|
+
this._assertInitialized();
|
|
214
|
+
key = this._withNs(key);
|
|
215
|
+
const { db, tableName } = this.options;
|
|
216
|
+
const expiresAt = new Date(Date.now() + ttl * 1000);
|
|
217
|
+
const { rowCount } = await db.query(`UPDATE ${tableName}
|
|
218
|
+
SET expires_at = $2, updated_at = NOW()
|
|
219
|
+
WHERE key = $1 AND (expires_at IS NULL OR expires_at > NOW())`, [key, expiresAt]);
|
|
220
|
+
return rowCount > 0;
|
|
221
|
+
}
|
|
222
|
+
/** Will get the expiration Date for given key */
|
|
223
|
+
async ttl(key) {
|
|
224
|
+
this._assertInitialized();
|
|
225
|
+
key = this._withNs(key);
|
|
226
|
+
const { db, tableName } = this.options;
|
|
227
|
+
const { rows } = await db.query(`SELECT expires_at FROM ${tableName} WHERE key = $1`, [key]);
|
|
228
|
+
// Key doesn't exist
|
|
229
|
+
if (rows.length === 0)
|
|
230
|
+
return false;
|
|
231
|
+
const expiresAt = rows[0].expires_at;
|
|
232
|
+
// No expiration set
|
|
233
|
+
if (!expiresAt)
|
|
234
|
+
return null;
|
|
235
|
+
return new Date(expiresAt);
|
|
236
|
+
}
|
|
237
|
+
/** */
|
|
238
|
+
async transaction(operations) {
|
|
239
|
+
this._assertInitialized();
|
|
240
|
+
const { db, logger } = this.options;
|
|
241
|
+
const results = [];
|
|
242
|
+
await db.query("BEGIN");
|
|
243
|
+
try {
|
|
244
|
+
for (const op of operations) {
|
|
245
|
+
switch (op.type) {
|
|
246
|
+
case "set":
|
|
247
|
+
results.push(await this.set(op.key, op.value, op.options || {}));
|
|
248
|
+
break;
|
|
249
|
+
case "get":
|
|
250
|
+
results.push(await this.get(op.key));
|
|
251
|
+
break;
|
|
252
|
+
case "delete":
|
|
253
|
+
results.push(await this.delete(op.key));
|
|
254
|
+
break;
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
await db.query("COMMIT");
|
|
258
|
+
}
|
|
259
|
+
catch (err) {
|
|
260
|
+
await db.query("ROLLBACK");
|
|
261
|
+
logger?.error?.(err);
|
|
262
|
+
throw err;
|
|
263
|
+
}
|
|
264
|
+
return results;
|
|
265
|
+
}
|
|
266
|
+
async __debug_dump() {
|
|
267
|
+
this._assertInitialized();
|
|
268
|
+
const { db, tableName } = this.options;
|
|
269
|
+
const { rows } = await db.query(`SELECT key, value, expires_at FROM ${tableName} WHERE key LIKE $1`, [this.namespace + "%"]);
|
|
270
|
+
// console.log(12312, rows);
|
|
271
|
+
return rows.reduce((m, row) => {
|
|
272
|
+
m[this._withoutNs(row.key)] = {
|
|
273
|
+
value: row.value,
|
|
274
|
+
ttl: row.expires_at,
|
|
275
|
+
};
|
|
276
|
+
return m;
|
|
277
|
+
}, {});
|
|
278
|
+
}
|
|
279
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { createClient, createClientPool } from "redis";
|
|
2
|
+
import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetOptions } from "./abstract.js";
|
|
3
|
+
export interface AdapterRedisOptions extends AdapterAbstractOptions {
|
|
4
|
+
db: ReturnType<typeof createClient> | ReturnType<typeof createClientPool>;
|
|
5
|
+
isCluster: boolean;
|
|
6
|
+
}
|
|
7
|
+
export declare class AdapterRedis extends AdapterAbstract {
|
|
8
|
+
readonly namespace: string;
|
|
9
|
+
_type: string;
|
|
10
|
+
readonly options: AdapterRedisOptions;
|
|
11
|
+
constructor(namespace?: string, options?: Partial<AdapterRedisOptions>);
|
|
12
|
+
initialize(): Promise<void>;
|
|
13
|
+
destroy(_hard?: boolean): Promise<void>;
|
|
14
|
+
/** Will set key-value pair to the underlying store with given options */
|
|
15
|
+
set(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
16
|
+
/** Will get the key from the underlying store */
|
|
17
|
+
get(key: string): Promise<any>;
|
|
18
|
+
/** Will delete the key from the underlying store */
|
|
19
|
+
delete(key: string): Promise<boolean>;
|
|
20
|
+
/** Will check if the key exists in the underlying store */
|
|
21
|
+
exists(key: string): Promise<boolean>;
|
|
22
|
+
/** Will list all existing keys in the underlying store matching given pattern.
|
|
23
|
+
* Recognizes redis-like star wildcard format. */
|
|
24
|
+
keys(pattern: string): Promise<string[]>;
|
|
25
|
+
/** Will clear all existing keys in the underlying store matching given pattern */
|
|
26
|
+
clear(pattern: string): Promise<number>;
|
|
27
|
+
/** Will set multiple kv pairs in one batch */
|
|
28
|
+
setMultiple(keyValuePairs: [string, any][], options?: Partial<SetOptions>): Promise<boolean[]>;
|
|
29
|
+
/** Will get multiple keys in one batch */
|
|
30
|
+
getMultiple(keys: string[]): Promise<Record<string, any>>;
|
|
31
|
+
/** Will set the expiration ttl on the given key to given ttl value */
|
|
32
|
+
expire(key: string, ttl: number): Promise<boolean>;
|
|
33
|
+
/** Will get the expiration Date for given key */
|
|
34
|
+
ttl(key: string): Promise<Date | null | false>;
|
|
35
|
+
/** */
|
|
36
|
+
transaction(operations: Operation[]): Promise<any[]>;
|
|
37
|
+
__debug_dump(): Promise<Record<string, {
|
|
38
|
+
value: any;
|
|
39
|
+
ttl: Date | null | false;
|
|
40
|
+
}>>;
|
|
41
|
+
}
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
import { AdapterAbstract, } from "./abstract.js";
|
|
2
|
+
import { createLogger } from "@marianmeres/clog";
|
|
3
|
+
export class AdapterRedis extends AdapterAbstract {
|
|
4
|
+
namespace;
|
|
5
|
+
_type = "redis";
|
|
6
|
+
options = {
|
|
7
|
+
defaultTtl: 0, // no ttl by default
|
|
8
|
+
logger: createLogger("KV/redis"),
|
|
9
|
+
db: null,
|
|
10
|
+
isCluster: false,
|
|
11
|
+
};
|
|
12
|
+
constructor(namespace = "", options = {}) {
|
|
13
|
+
super();
|
|
14
|
+
this.namespace = namespace;
|
|
15
|
+
if (!this.namespace) {
|
|
16
|
+
throw new Error(`Missing namespace (required in RedisAdapter)`);
|
|
17
|
+
}
|
|
18
|
+
this._assertValidNamespace();
|
|
19
|
+
this.options = Object.freeze({ ...this.options, ...(options || {}) });
|
|
20
|
+
if (!this.options.db) {
|
|
21
|
+
throw new Error("Missing redis db client instance");
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
async initialize() {
|
|
25
|
+
const { db, logger } = this.options;
|
|
26
|
+
db.on("error", (err) => logger?.error?.(err));
|
|
27
|
+
// the pool instance doesn't have connect, so being defensive...
|
|
28
|
+
if (!db.isOpen)
|
|
29
|
+
await db?.connect();
|
|
30
|
+
this._initialized = true;
|
|
31
|
+
}
|
|
32
|
+
destroy(_hard) {
|
|
33
|
+
this._initialized = false;
|
|
34
|
+
return Promise.resolve();
|
|
35
|
+
}
|
|
36
|
+
/** Will set key-value pair to the underlying store with given options */
|
|
37
|
+
async set(key, value, options = {}) {
|
|
38
|
+
this._assertInitialized();
|
|
39
|
+
key = this._withNs(key);
|
|
40
|
+
const { db } = this.options;
|
|
41
|
+
const ttl = options.ttl || this.options.defaultTtl || undefined;
|
|
42
|
+
if (value === undefined)
|
|
43
|
+
value = null; // redis does not accept undefined
|
|
44
|
+
value = JSON.stringify(value);
|
|
45
|
+
const r = await db.set(key, value, { EX: ttl });
|
|
46
|
+
return r === "OK";
|
|
47
|
+
}
|
|
48
|
+
/** Will get the key from the underlying store */
|
|
49
|
+
async get(key) {
|
|
50
|
+
this._assertInitialized();
|
|
51
|
+
key = this._withNs(key);
|
|
52
|
+
const { db } = this.options;
|
|
53
|
+
const value = await db.get(key);
|
|
54
|
+
if (value === null)
|
|
55
|
+
return null;
|
|
56
|
+
try {
|
|
57
|
+
return JSON.parse(`${value}`);
|
|
58
|
+
}
|
|
59
|
+
catch (_err) {
|
|
60
|
+
return value;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
/** Will delete the key from the underlying store */
|
|
64
|
+
async delete(key) {
|
|
65
|
+
this._assertInitialized();
|
|
66
|
+
key = this._withNs(key);
|
|
67
|
+
const { db } = this.options;
|
|
68
|
+
return parseInt((await db.del(key))) > 0;
|
|
69
|
+
}
|
|
70
|
+
/** Will check if the key exists in the underlying store */
|
|
71
|
+
async exists(key) {
|
|
72
|
+
this._assertInitialized();
|
|
73
|
+
key = this._withNs(key);
|
|
74
|
+
const { db } = this.options;
|
|
75
|
+
return (await db.exists(key)) === 1;
|
|
76
|
+
}
|
|
77
|
+
/** Will list all existing keys in the underlying store matching given pattern.
|
|
78
|
+
* Recognizes redis-like star wildcard format. */
|
|
79
|
+
async keys(pattern) {
|
|
80
|
+
this._assertInitialized();
|
|
81
|
+
const { db, isCluster } = this.options;
|
|
82
|
+
if (isCluster) {
|
|
83
|
+
throw new Error("KEYS command not supported in Redis Cluster mode");
|
|
84
|
+
}
|
|
85
|
+
const keys = (await db.keys(this.namespace + pattern));
|
|
86
|
+
return keys
|
|
87
|
+
.map((k) => {
|
|
88
|
+
// strip namespace if exists
|
|
89
|
+
if (this.namespace)
|
|
90
|
+
k = k.slice(this.namespace.length);
|
|
91
|
+
return k;
|
|
92
|
+
})
|
|
93
|
+
.toSorted();
|
|
94
|
+
}
|
|
95
|
+
/** Will clear all existing keys in the underlying store matching given pattern */
|
|
96
|
+
async clear(pattern) {
|
|
97
|
+
this._assertInitialized();
|
|
98
|
+
const { db, isCluster } = this.options;
|
|
99
|
+
if (isCluster) {
|
|
100
|
+
throw new Error("Pattern-based clear is not supported in Redis Cluster mode");
|
|
101
|
+
}
|
|
102
|
+
const keys = await this.keys(pattern);
|
|
103
|
+
if (keys.length === 0)
|
|
104
|
+
return 0;
|
|
105
|
+
return parseInt((await db.del(keys.map((k) => this._withNs(k)))));
|
|
106
|
+
}
|
|
107
|
+
/** Will set multiple kv pairs in one batch */
|
|
108
|
+
async setMultiple(keyValuePairs, options = {}) {
|
|
109
|
+
this._assertInitialized();
|
|
110
|
+
const { db } = this.options;
|
|
111
|
+
const ttl = options.ttl || this.options.defaultTtl || undefined;
|
|
112
|
+
const pipeline = db.multi();
|
|
113
|
+
for (let [key, value] of keyValuePairs) {
|
|
114
|
+
key = this._withNs(key);
|
|
115
|
+
pipeline.set(key, JSON.stringify(value), { EX: ttl });
|
|
116
|
+
}
|
|
117
|
+
const res = await pipeline.exec();
|
|
118
|
+
return res.map((v) => v === "OK");
|
|
119
|
+
}
|
|
120
|
+
/** Will get multiple keys in one batch */
|
|
121
|
+
async getMultiple(keys) {
|
|
122
|
+
this._assertInitialized();
|
|
123
|
+
const { db } = this.options;
|
|
124
|
+
keys = keys.map((k) => this._withNs(k));
|
|
125
|
+
const values = await db.mGet(keys);
|
|
126
|
+
const result = {};
|
|
127
|
+
keys.forEach((key, index) => {
|
|
128
|
+
key = this._withoutNs(key);
|
|
129
|
+
const value = values[index];
|
|
130
|
+
if (value !== null) {
|
|
131
|
+
try {
|
|
132
|
+
result[key] = JSON.parse(`${value}`);
|
|
133
|
+
}
|
|
134
|
+
catch (_err) {
|
|
135
|
+
result[key] = value;
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
else {
|
|
139
|
+
result[key] = null;
|
|
140
|
+
}
|
|
141
|
+
});
|
|
142
|
+
return result;
|
|
143
|
+
}
|
|
144
|
+
/** Will set the expiration ttl on the given key to given ttl value */
|
|
145
|
+
async expire(key, ttl) {
|
|
146
|
+
this._assertInitialized();
|
|
147
|
+
key = this._withNs(key);
|
|
148
|
+
return parseInt((await this.options.db.expire(key, ttl))) > 0;
|
|
149
|
+
}
|
|
150
|
+
/** Will get the expiration Date for given key */
|
|
151
|
+
async ttl(key) {
|
|
152
|
+
this._assertInitialized();
|
|
153
|
+
key = this._withNs(key);
|
|
154
|
+
const ttl = await this.options.db.ttl(key);
|
|
155
|
+
// Key doesn't exist
|
|
156
|
+
if (ttl === -2)
|
|
157
|
+
return false;
|
|
158
|
+
// No expiration set
|
|
159
|
+
if (ttl === -1)
|
|
160
|
+
return null;
|
|
161
|
+
// Positive number: TTL in seconds remaining
|
|
162
|
+
return new Date(Date.now() + parseInt(`${ttl}`) * 1_000);
|
|
163
|
+
}
|
|
164
|
+
/** */
|
|
165
|
+
async transaction(operations) {
|
|
166
|
+
this._assertInitialized();
|
|
167
|
+
const { db } = this.options;
|
|
168
|
+
const multi = db.multi();
|
|
169
|
+
for (const op of operations) {
|
|
170
|
+
const key = this._withNs(op.key);
|
|
171
|
+
switch (op.type) {
|
|
172
|
+
case "set":
|
|
173
|
+
multi.set(key, JSON.stringify(op.value));
|
|
174
|
+
break;
|
|
175
|
+
case "get":
|
|
176
|
+
multi.get(key);
|
|
177
|
+
break;
|
|
178
|
+
case "delete":
|
|
179
|
+
multi.del(key);
|
|
180
|
+
break;
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
const res = await multi.exec();
|
|
184
|
+
// fix results types
|
|
185
|
+
for (const [i, op] of operations.entries()) {
|
|
186
|
+
switch (op.type) {
|
|
187
|
+
case "set":
|
|
188
|
+
res[i] = res[i] === "OK";
|
|
189
|
+
break;
|
|
190
|
+
case "get":
|
|
191
|
+
try {
|
|
192
|
+
res[i] = JSON.parse(res[i]);
|
|
193
|
+
}
|
|
194
|
+
catch (_e) {
|
|
195
|
+
/**/
|
|
196
|
+
}
|
|
197
|
+
break;
|
|
198
|
+
case "delete":
|
|
199
|
+
res[i] = res[i] > 0;
|
|
200
|
+
break;
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
return res;
|
|
204
|
+
}
|
|
205
|
+
// this is not optimal quick-n-dirty implementation
|
|
206
|
+
// DO NOT USE for production data
|
|
207
|
+
async __debug_dump() {
|
|
208
|
+
this._assertInitialized();
|
|
209
|
+
const { db } = this.options;
|
|
210
|
+
const keys = (await db.keys("*")).toSorted();
|
|
211
|
+
const out = {};
|
|
212
|
+
for (const _key of keys) {
|
|
213
|
+
const key = this._withoutNs(_key);
|
|
214
|
+
out[key] = {
|
|
215
|
+
value: await this.get(key),
|
|
216
|
+
ttl: await this.ttl(key),
|
|
217
|
+
};
|
|
218
|
+
}
|
|
219
|
+
return out;
|
|
220
|
+
}
|
|
221
|
+
}
|
package/dist/kv.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { AdapterMemory, type AdapterMemoryOptions } from "./adapter/memory.js";
|
|
2
|
+
import { AdapterPostgres, type AdapterPostgresOptions } from "./adapter/postgres.js";
|
|
3
|
+
import { AdapterRedis, type AdapterRedisOptions } from "./adapter/redis.js";
|
|
4
|
+
interface KnownTypes {
|
|
5
|
+
memory: {
|
|
6
|
+
options: AdapterMemoryOptions;
|
|
7
|
+
adapter: AdapterMemory;
|
|
8
|
+
};
|
|
9
|
+
postgres: {
|
|
10
|
+
options: AdapterPostgresOptions;
|
|
11
|
+
adapter: AdapterPostgres;
|
|
12
|
+
};
|
|
13
|
+
redis: {
|
|
14
|
+
options: AdapterRedisOptions;
|
|
15
|
+
adapter: AdapterRedis;
|
|
16
|
+
};
|
|
17
|
+
}
|
|
18
|
+
/** */
|
|
19
|
+
export declare function createKVClient<T extends keyof KnownTypes>(namespace?: string, type?: T, options?: Partial<KnownTypes[T]["options"]>): KnownTypes[T]["adapter"];
|
|
20
|
+
export {};
|
package/dist/kv.js
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { AdapterMemory } from "./adapter/memory.js";
|
|
2
|
+
import { AdapterPostgres, } from "./adapter/postgres.js";
|
|
3
|
+
import { AdapterRedis } from "./adapter/redis.js";
|
|
4
|
+
/** */
|
|
5
|
+
export function createKVClient(namespace = "", type = "redis", options = {}) {
|
|
6
|
+
//
|
|
7
|
+
if (type === "memory")
|
|
8
|
+
return new AdapterMemory(namespace, options);
|
|
9
|
+
if (type === "postgres")
|
|
10
|
+
return new AdapterPostgres(namespace, options);
|
|
11
|
+
if (type === "redis")
|
|
12
|
+
return new AdapterRedis(namespace, options);
|
|
13
|
+
//
|
|
14
|
+
throw new TypeError(`Unsupported KV client type "${options.type}"`);
|
|
15
|
+
}
|
package/dist/mod.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./kv.js";
|
package/dist/mod.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./kv.js";
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Delays execution for `timeout` milliseconds.
|
|
3
|
+
*
|
|
4
|
+
* @example
|
|
5
|
+
* ```ts
|
|
6
|
+
* await sleep(100);
|
|
7
|
+
* ```
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* ```ts
|
|
11
|
+
* // Usage with timer reference
|
|
12
|
+
* let ref = { id: -1 };
|
|
13
|
+
* some(() => sleep(100, ref))
|
|
14
|
+
* // ...
|
|
15
|
+
* clearTimeout(ref.id)
|
|
16
|
+
* ```
|
|
17
|
+
*/
|
|
18
|
+
export declare function sleep(timeout: number,
|
|
19
|
+
/**
|
|
20
|
+
* Deno.test is quite strict and reports every non-cleared timeout... so we have to
|
|
21
|
+
* be able to pass in some object ref if needed (eg when sleep is not resolved via Promise.race)
|
|
22
|
+
* to be able to do the clearing eventually.
|
|
23
|
+
*
|
|
24
|
+
* If calling directly `await sleep(x)` in a top level flow, this dance is not needed.
|
|
25
|
+
*/
|
|
26
|
+
__timeout_ref__?: {
|
|
27
|
+
id: number;
|
|
28
|
+
}): Promise<void>;
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
// deno-lint-ignore-file no-explicit-any
|
|
2
|
+
/**
|
|
3
|
+
* Delays execution for `timeout` milliseconds.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* await sleep(100);
|
|
8
|
+
* ```
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* ```ts
|
|
12
|
+
* // Usage with timer reference
|
|
13
|
+
* let ref = { id: -1 };
|
|
14
|
+
* some(() => sleep(100, ref))
|
|
15
|
+
* // ...
|
|
16
|
+
* clearTimeout(ref.id)
|
|
17
|
+
* ```
|
|
18
|
+
*/
|
|
19
|
+
export function sleep(timeout,
|
|
20
|
+
/**
|
|
21
|
+
* Deno.test is quite strict and reports every non-cleared timeout... so we have to
|
|
22
|
+
* be able to pass in some object ref if needed (eg when sleep is not resolved via Promise.race)
|
|
23
|
+
* to be able to do the clearing eventually.
|
|
24
|
+
*
|
|
25
|
+
* If calling directly `await sleep(x)` in a top level flow, this dance is not needed.
|
|
26
|
+
*/
|
|
27
|
+
__timeout_ref__ = { id: -1 }) {
|
|
28
|
+
return new Promise((resolve) => {
|
|
29
|
+
__timeout_ref__.id = setTimeout(() => {
|
|
30
|
+
clearTimeout(__timeout_ref__.id);
|
|
31
|
+
resolve(undefined);
|
|
32
|
+
}, timeout);
|
|
33
|
+
});
|
|
34
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@marianmeres/kv",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"main": "dist/mod.js",
|
|
6
|
+
"types": "dist/mod.d.ts",
|
|
7
|
+
"author": "Marian Meres",
|
|
8
|
+
"license": "MIT",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "git+https://github.com/marianmeres/kv.git"
|
|
12
|
+
},
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/marianmeres/kv/issues"
|
|
15
|
+
},
|
|
16
|
+
"dependencies": {
|
|
17
|
+
"@marianmeres/clog": "^2.3.3",
|
|
18
|
+
"pg": "^8.16.3",
|
|
19
|
+
"redis": "^5.6.1"
|
|
20
|
+
},
|
|
21
|
+
"devDependencies": {
|
|
22
|
+
"@types/node": "latest",
|
|
23
|
+
"@types/pg": "latest"
|
|
24
|
+
}
|
|
25
|
+
}
|