@c9up/echo 0.2.3 → 0.2.5
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/README.md +1 -1
- package/dist/CacheManager.d.ts +13 -2
- package/dist/CacheManager.d.ts.map +1 -1
- package/dist/CacheManager.js +309 -56
- package/dist/CacheManager.js.map +1 -1
- package/dist/EchoProvider.d.ts.map +1 -1
- package/dist/EchoProvider.js +32 -3
- package/dist/EchoProvider.js.map +1 -1
- package/dist/StoreManager.d.ts +38 -11
- package/dist/StoreManager.d.ts.map +1 -1
- package/dist/StoreManager.js +80 -22
- package/dist/StoreManager.js.map +1 -1
- package/dist/bytes.d.ts +13 -0
- package/dist/bytes.d.ts.map +1 -0
- package/dist/bytes.js +35 -0
- package/dist/bytes.js.map +1 -0
- package/dist/claim.d.ts +15 -0
- package/dist/claim.d.ts.map +1 -0
- package/dist/claim.js +10 -0
- package/dist/claim.js.map +1 -0
- package/dist/configure.d.ts +1 -0
- package/dist/configure.d.ts.map +1 -1
- package/dist/configure.js +3 -0
- package/dist/configure.js.map +1 -1
- package/dist/console/cacheClear.d.ts +13 -0
- package/dist/console/cacheClear.d.ts.map +1 -0
- package/dist/console/cacheClear.js +69 -0
- package/dist/console/cacheClear.js.map +1 -0
- package/dist/console/cacheDelete.d.ts +11 -0
- package/dist/console/cacheDelete.d.ts.map +1 -0
- package/dist/console/cacheDelete.js +42 -0
- package/dist/console/cacheDelete.js.map +1 -0
- package/dist/console/cachePrune.d.ts +9 -0
- package/dist/console/cachePrune.d.ts.map +1 -0
- package/dist/console/cachePrune.js +35 -0
- package/dist/console/cachePrune.js.map +1 -0
- package/dist/console/contract.d.ts +64 -0
- package/dist/console/contract.d.ts.map +1 -0
- package/dist/console/contract.js +32 -0
- package/dist/console/contract.js.map +1 -0
- package/dist/console/index.d.ts +25 -0
- package/dist/console/index.d.ts.map +1 -0
- package/dist/console/index.js +38 -0
- package/dist/console/index.js.map +1 -0
- package/dist/console/store.d.ts +14 -0
- package/dist/console/store.d.ts.map +1 -0
- package/dist/console/store.js +35 -0
- package/dist/console/store.js.map +1 -0
- package/dist/drivers/MemoryDriver.d.ts +37 -1
- package/dist/drivers/MemoryDriver.d.ts.map +1 -1
- package/dist/drivers/MemoryDriver.js +170 -72
- package/dist/drivers/MemoryDriver.js.map +1 -1
- package/dist/drivers/RedisDriver.d.ts +15 -8
- package/dist/drivers/RedisDriver.d.ts.map +1 -1
- package/dist/drivers/RedisDriver.js +198 -97
- package/dist/drivers/RedisDriver.js.map +1 -1
- package/dist/drivers/TieredDriver.d.ts +42 -0
- package/dist/drivers/TieredDriver.d.ts.map +1 -1
- package/dist/drivers/TieredDriver.js +114 -9
- package/dist/drivers/TieredDriver.js.map +1 -1
- package/dist/duration.d.ts +13 -3
- package/dist/duration.d.ts.map +1 -1
- package/dist/duration.js +22 -7
- package/dist/duration.js.map +1 -1
- package/dist/errors.d.ts +60 -2
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +81 -6
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +4 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/dist/quasar.d.ts +1 -1
- package/dist/quasar.d.ts.map +1 -1
- package/dist/quasar.js +106 -19
- package/dist/quasar.js.map +1 -1
- package/dist/services/main.d.ts +1 -1
- package/dist/services/main.d.ts.map +1 -1
- package/dist/services/main.js +22 -5
- package/dist/services/main.js.map +1 -1
- package/dist/types.d.ts +44 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/vendor/quasarConnection.d.ts +44 -3
- package/dist/vendor/quasarConnection.d.ts.map +1 -1
- package/dist/vendor/quasarConnection.js +64 -23
- package/dist/vendor/quasarConnection.js.map +1 -1
- package/package.json +5 -1
- package/src/CacheManager.ts +367 -69
- package/src/EchoProvider.ts +45 -4
- package/src/StoreManager.ts +131 -35
- package/src/bytes.ts +38 -0
- package/src/claim.ts +22 -0
- package/src/configure.ts +4 -0
- package/src/console/cacheClear.ts +96 -0
- package/src/console/cacheDelete.ts +65 -0
- package/src/console/cachePrune.ts +57 -0
- package/src/console/contract.ts +93 -0
- package/src/console/index.ts +61 -0
- package/src/console/store.ts +47 -0
- package/src/drivers/MemoryDriver.ts +221 -69
- package/src/drivers/RedisDriver.ts +234 -104
- package/src/drivers/TieredDriver.ts +169 -9
- package/src/duration.ts +28 -7
- package/src/errors.ts +103 -6
- package/src/index.ts +17 -3
- package/src/quasar.ts +145 -30
- package/src/services/main.ts +26 -8
- package/src/types.ts +46 -7
- package/src/vendor/quasarConnection.ts +105 -22
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The console command contract, declared locally.
|
|
3
|
+
*
|
|
4
|
+
* Echo stays framework-agnostic: it must not import `@c9up/ream`, so it
|
|
5
|
+
* describes the shape Ream's console kernel dispatches against rather than
|
|
6
|
+
* importing it. The kernel assigns `logger`, `prompt` and — for a command that
|
|
7
|
+
* starts the app — `app` before it calls `run()`.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
export interface CommandOptions {
|
|
11
|
+
/** Boot the application before `run()`. */
|
|
12
|
+
startApp?: boolean;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export interface ArgumentMetaData {
|
|
16
|
+
type: "string" | "spread";
|
|
17
|
+
propertyName: string;
|
|
18
|
+
argumentName: string;
|
|
19
|
+
description?: string;
|
|
20
|
+
required: boolean;
|
|
21
|
+
default?: string | string[];
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export interface FlagMetaData {
|
|
25
|
+
type: "string" | "boolean" | "number" | "array";
|
|
26
|
+
propertyName: string;
|
|
27
|
+
flagName: string;
|
|
28
|
+
description?: string;
|
|
29
|
+
alias: string[];
|
|
30
|
+
default?: string | string[] | number | boolean;
|
|
31
|
+
required: boolean;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** The slice of the kernel's logger these commands write to. */
|
|
35
|
+
export interface CommandLogger {
|
|
36
|
+
success(message: string): void;
|
|
37
|
+
warning(message: string): void;
|
|
38
|
+
error(message: string): void;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** The slice of the kernel's prompt these commands ask through. */
|
|
42
|
+
export interface CommandPrompt {
|
|
43
|
+
confirm(message: string): Promise<boolean>;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** The slice of the booted application these commands read. */
|
|
47
|
+
export interface CommandApp {
|
|
48
|
+
readonly inProduction: boolean;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** The static side the kernel reads. */
|
|
52
|
+
export interface EchoCommandClass {
|
|
53
|
+
new (): { run(): Promise<void> | void };
|
|
54
|
+
commandName: string;
|
|
55
|
+
description: string;
|
|
56
|
+
options?: CommandOptions;
|
|
57
|
+
args?: readonly ArgumentMetaData[];
|
|
58
|
+
flags?: readonly FlagMetaData[];
|
|
59
|
+
help?: string | string[];
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** `startServer` → `start-server`, matching the framework's decorators. */
|
|
63
|
+
function dashCase(value: string): string {
|
|
64
|
+
return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
export function flag(
|
|
68
|
+
propertyName: string,
|
|
69
|
+
type: FlagMetaData["type"],
|
|
70
|
+
options: { description?: string; alias?: string[] } = {},
|
|
71
|
+
): FlagMetaData {
|
|
72
|
+
return {
|
|
73
|
+
type,
|
|
74
|
+
propertyName,
|
|
75
|
+
flagName: dashCase(propertyName),
|
|
76
|
+
description: options.description,
|
|
77
|
+
alias: options.alias ?? [],
|
|
78
|
+
required: false,
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
export function argument(
|
|
83
|
+
propertyName: string,
|
|
84
|
+
options: { description?: string; required?: boolean } = {},
|
|
85
|
+
): ArgumentMetaData {
|
|
86
|
+
return {
|
|
87
|
+
type: "string",
|
|
88
|
+
propertyName,
|
|
89
|
+
argumentName: dashCase(propertyName),
|
|
90
|
+
description: options.description,
|
|
91
|
+
required: options.required ?? true,
|
|
92
|
+
};
|
|
93
|
+
}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@c9up/echo/commands` — the commands echo ships.
|
|
3
|
+
*
|
|
4
|
+
* // reamrc.ts, written by `configure()`
|
|
5
|
+
* commands: [() => import('@c9up/echo/commands')]
|
|
6
|
+
*
|
|
7
|
+
* A module answering `getMetaData()` / `getCommand()`, which is how a package
|
|
8
|
+
* adds commands: by shipping them, never by a change to the `ream` binary.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { cacheClearCommand } from "./cacheClear.js";
|
|
12
|
+
import { cacheDeleteCommand } from "./cacheDelete.js";
|
|
13
|
+
import { cachePruneCommand } from "./cachePrune.js";
|
|
14
|
+
import type { EchoCommandClass } from "./contract.js";
|
|
15
|
+
|
|
16
|
+
const COMMANDS: readonly EchoCommandClass[] = [
|
|
17
|
+
cacheClearCommand(),
|
|
18
|
+
cacheDeleteCommand(),
|
|
19
|
+
cachePruneCommand(),
|
|
20
|
+
];
|
|
21
|
+
|
|
22
|
+
/** What the kernel reads to list a command without importing it. */
|
|
23
|
+
interface CommandMetaData {
|
|
24
|
+
commandName: string;
|
|
25
|
+
namespace: string | null;
|
|
26
|
+
description: string;
|
|
27
|
+
help?: string | string[];
|
|
28
|
+
aliases: string[];
|
|
29
|
+
options: Record<string, unknown>;
|
|
30
|
+
args: readonly unknown[];
|
|
31
|
+
flags: readonly unknown[];
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function serialize(command: EchoCommandClass): CommandMetaData {
|
|
35
|
+
const colon = command.commandName.indexOf(":");
|
|
36
|
+
return {
|
|
37
|
+
commandName: command.commandName,
|
|
38
|
+
namespace: colon === -1 ? null : command.commandName.slice(0, colon),
|
|
39
|
+
description: command.description,
|
|
40
|
+
help: command.help,
|
|
41
|
+
aliases: [],
|
|
42
|
+
options: { ...command.options },
|
|
43
|
+
args: command.args ?? [],
|
|
44
|
+
flags: command.flags ?? [],
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export async function getMetaData(): Promise<CommandMetaData[]> {
|
|
49
|
+
return COMMANDS.map(serialize);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export async function getCommand(
|
|
53
|
+
metadata: CommandMetaData,
|
|
54
|
+
): Promise<EchoCommandClass | null> {
|
|
55
|
+
return (
|
|
56
|
+
COMMANDS.find((command) => command.commandName === metadata.commandName) ??
|
|
57
|
+
null
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export type { EchoCommandClass } from "./contract.js";
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the three cache commands share: reaching the store they were given,
|
|
3
|
+
* and asking before they touch a production cache.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import type { CacheManager } from "../CacheManager.js";
|
|
7
|
+
import { getCache } from "../services/main.js";
|
|
8
|
+
import type { CommandLogger, CommandPrompt } from "./contract.js";
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* The store a command names, or the default one — `undefined` after reporting
|
|
12
|
+
* why there is none, so the command can stop with a non-zero exit.
|
|
13
|
+
*/
|
|
14
|
+
export function resolveStore(
|
|
15
|
+
name: string | undefined,
|
|
16
|
+
logger: CommandLogger,
|
|
17
|
+
): CacheManager | undefined {
|
|
18
|
+
const cache = getCache();
|
|
19
|
+
if (cache === undefined) {
|
|
20
|
+
// Naming the wiring beats a stack trace out of the service proxy: the
|
|
21
|
+
// usual cause is a project that never added the provider.
|
|
22
|
+
logger.error(
|
|
23
|
+
"No cache is configured. Add `() => import('@c9up/echo/provider')` to the providers in reamrc.ts.",
|
|
24
|
+
);
|
|
25
|
+
return undefined;
|
|
26
|
+
}
|
|
27
|
+
try {
|
|
28
|
+
return cache.use(name);
|
|
29
|
+
} catch {
|
|
30
|
+
logger.error(
|
|
31
|
+
`"${name ?? "default"}" is not a valid cache store. Double check config/cache.ts file`,
|
|
32
|
+
);
|
|
33
|
+
return undefined;
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** A yes from the operator; a prompt that cannot be answered is a no. */
|
|
38
|
+
export async function consent(
|
|
39
|
+
prompt: CommandPrompt,
|
|
40
|
+
question: string,
|
|
41
|
+
): Promise<boolean> {
|
|
42
|
+
try {
|
|
43
|
+
return await prompt.confirm(question);
|
|
44
|
+
} catch {
|
|
45
|
+
return false;
|
|
46
|
+
}
|
|
47
|
+
}
|
|
@@ -4,15 +4,65 @@
|
|
|
4
4
|
* as the L1 tier of {@link TieredDriver}.
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
|
+
import { parseBytes } from "../bytes.js";
|
|
8
|
+
import { claimed, hasUnref } from "../claim.js";
|
|
9
|
+
import { checkTtlSeconds } from "../duration.js";
|
|
10
|
+
import { EchoError, UndefinedValueError } from "../errors.js";
|
|
7
11
|
import type { CacheEntry, DriverSetOptions, TaggableDriver } from "../types.js";
|
|
8
12
|
|
|
13
|
+
export interface MemoryDriverOptions {
|
|
14
|
+
/** How often expired entries are swept, in milliseconds (default 60 000). */
|
|
15
|
+
sweepIntervalMs?: number;
|
|
16
|
+
/**
|
|
17
|
+
* How many entries the store holds before it evicts the least recently
|
|
18
|
+
* used. Default 1000, as upstream; `0` or `Infinity` for no ceiling.
|
|
19
|
+
*/
|
|
20
|
+
maxItems?: number;
|
|
21
|
+
/**
|
|
22
|
+
* Total size of the stored values, in bytes or as `'10mb'`; past it the
|
|
23
|
+
* least recently used entries go. Needs `serialize`, since it measures
|
|
24
|
+
* the JSON.
|
|
25
|
+
*/
|
|
26
|
+
maxSize?: number | string;
|
|
27
|
+
/**
|
|
28
|
+
* Largest single value, in bytes or as `'1mb'`. A bigger one is not
|
|
29
|
+
* stored, and the key's previous value goes with it. Defaults to
|
|
30
|
+
* `maxSize` when that is set, and a value over `maxSize` is never stored
|
|
31
|
+
* whatever this says. Needs `serialize`.
|
|
32
|
+
*/
|
|
33
|
+
maxEntrySize?: number | string;
|
|
34
|
+
/**
|
|
35
|
+
* Store values as JSON and hand out a fresh copy on every read (default).
|
|
36
|
+
*
|
|
37
|
+
* `false` keeps the caller's object and returns that same reference, which
|
|
38
|
+
* is faster and keeps class instances, Dates and Maps intact — but any
|
|
39
|
+
* reader that mutates what it got rewrites the value for every later one.
|
|
40
|
+
*/
|
|
41
|
+
serialize?: boolean;
|
|
42
|
+
}
|
|
43
|
+
|
|
9
44
|
interface StoredEntry {
|
|
45
|
+
/** The JSON text when the driver serializes, the value itself when it does not. */
|
|
10
46
|
value: unknown;
|
|
11
47
|
/** Logical expiry (epoch ms); `0` means never. Past this the entry is stale. */
|
|
12
48
|
expiresAt: number;
|
|
13
49
|
/** Physical eviction (epoch ms); `0` means never. Grace window ends here. */
|
|
14
50
|
staleUntil: number;
|
|
15
51
|
tags: string[];
|
|
52
|
+
/** Bytes of JSON; `0` when the driver keeps references. */
|
|
53
|
+
size: number;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** The JSON a value is stored as; refused when JSON cannot carry it. */
|
|
57
|
+
function toJson(value: unknown): string {
|
|
58
|
+
const json = JSON.stringify(value);
|
|
59
|
+
if (json === undefined) {
|
|
60
|
+
throw new EchoError(
|
|
61
|
+
"E_ECHO_UNSERIALIZABLE_VALUE",
|
|
62
|
+
"Echo: the memory driver stores values as JSON, and this one has no JSON form — pass `serialize: false` to keep it as is",
|
|
63
|
+
);
|
|
64
|
+
}
|
|
65
|
+
return json;
|
|
16
66
|
}
|
|
17
67
|
|
|
18
68
|
export class MemoryDriver implements TaggableDriver {
|
|
@@ -20,45 +70,96 @@ export class MemoryDriver implements TaggableDriver {
|
|
|
20
70
|
#tagIndex: Map<string, Set<string>> = new Map();
|
|
21
71
|
#sweepInterval: ReturnType<typeof setInterval>;
|
|
22
72
|
/**
|
|
23
|
-
* How many entries this driver holds before it
|
|
73
|
+
* How many entries this driver holds before it evicts.
|
|
24
74
|
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
* genuinely wants no ceiling.
|
|
75
|
+
* 1000 unless told otherwise, as upstream's LRU. It had no ceiling by
|
|
76
|
+
* default, so a cache keyed by anything a user controls — an id, a search
|
|
77
|
+
* term — grew until the process ran out of memory. `0` is an explicit "no
|
|
78
|
+
* ceiling".
|
|
30
79
|
*/
|
|
31
80
|
readonly #maxItems: number;
|
|
81
|
+
/** Byte bound on all values together; `0` for none. */
|
|
82
|
+
readonly #maxSize: number;
|
|
83
|
+
/** Byte bound on one value; `0` for none. */
|
|
84
|
+
readonly #maxEntrySize: number;
|
|
85
|
+
/** Bytes held, kept in step with every write and removal. */
|
|
86
|
+
#size = 0;
|
|
87
|
+
/**
|
|
88
|
+
* Whether values go in as JSON and come out as a copy.
|
|
89
|
+
*
|
|
90
|
+
* On by default, as upstream serializes its L1 by default: the driver kept
|
|
91
|
+
* the caller's object and returned that same reference, so a request that
|
|
92
|
+
* mutated what it read — a cached permission set, say — changed it for
|
|
93
|
+
* every later reader. JSON is also what the Redis driver stores, so a
|
|
94
|
+
* value reads back the same in development and in production.
|
|
95
|
+
*/
|
|
96
|
+
readonly #serialize: boolean;
|
|
32
97
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
98
|
+
/**
|
|
99
|
+
* @param options the options, or the sweep interval in milliseconds (the
|
|
100
|
+
* original positional form, kept with `maxItems` beside it).
|
|
101
|
+
*/
|
|
102
|
+
constructor(options: MemoryDriverOptions | number = {}, maxItems?: number) {
|
|
103
|
+
const config: MemoryDriverOptions =
|
|
104
|
+
typeof options === "number"
|
|
105
|
+
? { sweepIntervalMs: options, maxItems }
|
|
106
|
+
: options;
|
|
107
|
+
const ceiling = config.maxItems ?? 1000;
|
|
108
|
+
if (Number.isNaN(ceiling) || ceiling < 0) {
|
|
109
|
+
throw new EchoError(
|
|
110
|
+
"E_ECHO_INVALID_CONFIG",
|
|
111
|
+
`Echo: maxItems must be a count, 0 or Infinity for no ceiling — got ${String(ceiling)}`,
|
|
112
|
+
);
|
|
113
|
+
}
|
|
114
|
+
this.#maxItems = Number.isFinite(ceiling) ? ceiling : 0;
|
|
115
|
+
this.#serialize = config.serialize ?? true;
|
|
36
116
|
if (
|
|
37
|
-
|
|
38
|
-
|
|
117
|
+
!this.#serialize &&
|
|
118
|
+
(config.maxSize !== undefined || config.maxEntrySize !== undefined)
|
|
39
119
|
) {
|
|
40
|
-
|
|
120
|
+
// What it would measure is the JSON, and a driver keeping
|
|
121
|
+
// references has none. Upstream refuses the same combination.
|
|
122
|
+
throw new EchoError(
|
|
123
|
+
"E_ECHO_INVALID_CONFIG",
|
|
124
|
+
"Echo: maxSize and maxEntrySize measure the stored JSON, so they need `serialize` — drop `serialize: false` or the byte bound",
|
|
125
|
+
);
|
|
41
126
|
}
|
|
127
|
+
this.#maxSize =
|
|
128
|
+
config.maxSize === undefined ? 0 : parseBytes(config.maxSize, "maxSize");
|
|
129
|
+
this.#maxEntrySize =
|
|
130
|
+
config.maxEntrySize === undefined
|
|
131
|
+
? this.#maxSize
|
|
132
|
+
: parseBytes(config.maxEntrySize, "maxEntrySize");
|
|
133
|
+
this.#sweepInterval = setInterval(
|
|
134
|
+
() => this.#sweep(),
|
|
135
|
+
config.sweepIntervalMs ?? 60_000,
|
|
136
|
+
);
|
|
137
|
+
// The sweep is housekeeping, not a reason for the process to stay up.
|
|
138
|
+
if (hasUnref(this.#sweepInterval)) this.#sweepInterval.unref();
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
#fits(): boolean {
|
|
142
|
+
return (
|
|
143
|
+
(this.#maxItems === 0 || this.#store.size <= this.#maxItems) &&
|
|
144
|
+
(this.#maxSize === 0 || this.#size <= this.#maxSize)
|
|
145
|
+
);
|
|
42
146
|
}
|
|
43
147
|
|
|
44
148
|
/**
|
|
45
|
-
* Drop the
|
|
149
|
+
* Drop the least recently used entries until the store fits under its
|
|
150
|
+
* ceilings: the Map's order, since a read moves its key to the end as a
|
|
151
|
+
* write does.
|
|
46
152
|
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
153
|
+
* The least recently used, whatever has expired elsewhere in the order.
|
|
154
|
+
* Hunting for expired entries first walked the whole map on every write
|
|
155
|
+
* at the ceiling, a cost proportional to the ceiling a large working set
|
|
156
|
+
* pays on each write; expired entries are the sweep's, and a read drops
|
|
157
|
+
* one it finds. Upstream's LRU evicts the same way.
|
|
50
158
|
*/
|
|
51
159
|
#enforceCeiling(): void {
|
|
52
|
-
if (this.#
|
|
53
|
-
const now = Date.now();
|
|
54
|
-
for (const [key, entry] of this.#store) {
|
|
55
|
-
if (this.#store.size <= this.#maxItems) return;
|
|
56
|
-
if (entry.staleUntil > 0 && entry.staleUntil < now) {
|
|
57
|
-
this.#evict(key, entry);
|
|
58
|
-
}
|
|
59
|
-
}
|
|
160
|
+
if (this.#fits()) return;
|
|
60
161
|
for (const [key, entry] of this.#store) {
|
|
61
|
-
if (this.#
|
|
162
|
+
if (this.#fits()) return;
|
|
62
163
|
this.#evict(key, entry);
|
|
63
164
|
}
|
|
64
165
|
}
|
|
@@ -113,8 +214,21 @@ export class MemoryDriver implements TaggableDriver {
|
|
|
113
214
|
this.#evict(key, entry);
|
|
114
215
|
return null;
|
|
115
216
|
}
|
|
217
|
+
// Least recently USED, not written: a read moves the key to the end of
|
|
218
|
+
// the eviction order. Without it the hottest key was the first to go.
|
|
219
|
+
this.#store.delete(key);
|
|
220
|
+
this.#store.set(key, entry);
|
|
116
221
|
const stale = entry.expiresAt > 0 && entry.expiresAt < now;
|
|
117
|
-
|
|
222
|
+
const value =
|
|
223
|
+
this.#serialize && typeof entry.value === "string"
|
|
224
|
+
? JSON.parse(entry.value)
|
|
225
|
+
: entry.value;
|
|
226
|
+
return {
|
|
227
|
+
value: claimed<T>(value),
|
|
228
|
+
stale,
|
|
229
|
+
expiresAt: entry.expiresAt,
|
|
230
|
+
tags: [...entry.tags],
|
|
231
|
+
};
|
|
118
232
|
}
|
|
119
233
|
|
|
120
234
|
/**
|
|
@@ -124,8 +238,30 @@ export class MemoryDriver implements TaggableDriver {
|
|
|
124
238
|
* into a wrong-purge under deleteByTag (audit 2026-06-13).
|
|
125
239
|
*/
|
|
126
240
|
#evict(key: string, entry: StoredEntry): void {
|
|
127
|
-
|
|
241
|
+
this.#untag(key, entry.tags);
|
|
128
242
|
this.#store.delete(key);
|
|
243
|
+
this.#size -= entry.size;
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* Take `key` out of each tag's set, and drop a set it leaves empty.
|
|
248
|
+
*
|
|
249
|
+
* Emptied sets were kept, so per-user or per-id tags grew the index by one
|
|
250
|
+
* set per entry ever written: a store capped at ten entries held hundreds
|
|
251
|
+
* of megabytes of empty sets.
|
|
252
|
+
*/
|
|
253
|
+
#untag(key: string, tags: string[]): void {
|
|
254
|
+
for (const tag of tags) {
|
|
255
|
+
const keys = this.#tagIndex.get(tag);
|
|
256
|
+
if (keys === undefined) continue;
|
|
257
|
+
keys.delete(key);
|
|
258
|
+
if (keys.size === 0) this.#tagIndex.delete(tag);
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
/** How many tags the index holds — what bounds its memory, for diagnostics. */
|
|
263
|
+
tagCount(): number {
|
|
264
|
+
return this.#tagIndex.size;
|
|
129
265
|
}
|
|
130
266
|
|
|
131
267
|
#write(
|
|
@@ -137,21 +273,44 @@ export class MemoryDriver implements TaggableDriver {
|
|
|
137
273
|
expiresAtOverride?: number,
|
|
138
274
|
): void {
|
|
139
275
|
if (value === null || value === undefined) {
|
|
140
|
-
throw new
|
|
141
|
-
|
|
142
|
-
|
|
276
|
+
throw new UndefinedValueError();
|
|
277
|
+
}
|
|
278
|
+
// Before anything is touched: a value JSON cannot carry must leave the
|
|
279
|
+
// previous entry and its tags exactly as they were.
|
|
280
|
+
const stored = this.#serialize ? toJson(value) : value;
|
|
281
|
+
const size = typeof stored === "string" ? Buffer.byteLength(stored) : 0;
|
|
282
|
+
if (
|
|
283
|
+
(this.#maxEntrySize > 0 && size > this.#maxEntrySize) ||
|
|
284
|
+
(this.#maxSize > 0 && size > this.#maxSize)
|
|
285
|
+
) {
|
|
286
|
+
// Too big to keep. The previous value goes too, as upstream's LRU
|
|
287
|
+
// does: a skipped write must not leave an older value served. A
|
|
288
|
+
// value over the whole store's bound counts as too big whatever
|
|
289
|
+
// maxEntrySize says: inserted, it evicted every other entry and
|
|
290
|
+
// then itself.
|
|
291
|
+
this.#deleteEntry(key);
|
|
292
|
+
return;
|
|
143
293
|
}
|
|
144
294
|
const now = Date.now();
|
|
145
|
-
const
|
|
295
|
+
const ttl = ttlSeconds === undefined ? 0 : checkTtlSeconds(ttlSeconds);
|
|
296
|
+
const graceMs = graceSeconds > 0 ? graceSeconds * 1000 : 0;
|
|
297
|
+
if (expiresAtOverride === undefined && ttl < 0 && graceMs === 0) {
|
|
298
|
+
// Already expired, and no grace to keep a stale copy for: nothing
|
|
299
|
+
// to store, and the previous value must not survive it.
|
|
300
|
+
this.#deleteEntry(key);
|
|
301
|
+
return;
|
|
302
|
+
}
|
|
146
303
|
// An absolute `expiresAtOverride` (e.g. `expire()` marking stale-now) wins
|
|
147
|
-
// over the ttl-derived expiry; a past value makes the entry immediately
|
|
304
|
+
// over the ttl-derived expiry; a past value makes the entry immediately
|
|
305
|
+
// stale. So does a negative TTL — it never reads as "no expiry".
|
|
148
306
|
const expiresAt =
|
|
149
307
|
expiresAtOverride !== undefined
|
|
150
308
|
? expiresAtOverride
|
|
151
|
-
:
|
|
152
|
-
? now
|
|
153
|
-
: 0
|
|
154
|
-
|
|
309
|
+
: ttl < 0
|
|
310
|
+
? now - 1
|
|
311
|
+
: ttl > 0
|
|
312
|
+
? now + ttl * 1000
|
|
313
|
+
: 0;
|
|
155
314
|
// A never-expiring entry never goes stale either; otherwise grace extends
|
|
156
315
|
// physical retention past the logical expiry. Measure grace from the LATER
|
|
157
316
|
// of the expiry and now, so an already-past expiry still survives its grace.
|
|
@@ -160,15 +319,20 @@ export class MemoryDriver implements TaggableDriver {
|
|
|
160
319
|
// its old tag-index refs, or a later deleteByTag could purge this fresh
|
|
161
320
|
// value (audit 2026-05-22 F3).
|
|
162
321
|
const prev = this.#store.get(key);
|
|
163
|
-
if (prev !== undefined)
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
322
|
+
if (prev !== undefined) this.#evict(key, prev);
|
|
323
|
+
// Inserted last, so it is the most recently used.
|
|
324
|
+
this.#store.set(key, {
|
|
325
|
+
value: stored,
|
|
326
|
+
expiresAt,
|
|
327
|
+
staleUntil,
|
|
328
|
+
tags,
|
|
329
|
+
size,
|
|
330
|
+
});
|
|
331
|
+
this.#size += size;
|
|
332
|
+
// Indexed BEFORE the ceiling is enforced, so an eviction that takes
|
|
333
|
+
// this very entry untags it. Indexed after, an entry the ceiling had
|
|
334
|
+
// just dropped stayed in its tags' sets, and a later deleteByTag of
|
|
335
|
+
// one of them purged whatever value the key held by then.
|
|
172
336
|
for (const tag of tags) {
|
|
173
337
|
let set = this.#tagIndex.get(tag);
|
|
174
338
|
if (!set) {
|
|
@@ -177,6 +341,7 @@ export class MemoryDriver implements TaggableDriver {
|
|
|
177
341
|
}
|
|
178
342
|
set.add(key);
|
|
179
343
|
}
|
|
344
|
+
this.#enforceCeiling();
|
|
180
345
|
}
|
|
181
346
|
|
|
182
347
|
async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
|
|
@@ -199,30 +364,25 @@ export class MemoryDriver implements TaggableDriver {
|
|
|
199
364
|
}
|
|
200
365
|
|
|
201
366
|
async delete(key: string): Promise<boolean> {
|
|
367
|
+
return this.#deleteEntry(key);
|
|
368
|
+
}
|
|
369
|
+
|
|
370
|
+
#deleteEntry(key: string): boolean {
|
|
202
371
|
const entry = this.#store.get(key);
|
|
203
|
-
if (entry)
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
}
|
|
207
|
-
}
|
|
208
|
-
return this.#store.delete(key);
|
|
372
|
+
if (entry === undefined) return false;
|
|
373
|
+
this.#evict(key, entry);
|
|
374
|
+
return true;
|
|
209
375
|
}
|
|
210
376
|
|
|
211
377
|
async flush(prefix?: string): Promise<void> {
|
|
212
378
|
if (prefix === undefined) {
|
|
213
379
|
this.#store.clear();
|
|
214
380
|
this.#tagIndex.clear();
|
|
381
|
+
this.#size = 0;
|
|
215
382
|
return;
|
|
216
383
|
}
|
|
217
|
-
for (const key of [...this.#store
|
|
218
|
-
if (key.startsWith(prefix)) this.#
|
|
219
|
-
}
|
|
220
|
-
// The tag index points at keys; the ones that are gone go with them.
|
|
221
|
-
for (const [tag, keys] of [...this.#tagIndex.entries()]) {
|
|
222
|
-
for (const key of [...keys]) {
|
|
223
|
-
if (key.startsWith(prefix)) keys.delete(key);
|
|
224
|
-
}
|
|
225
|
-
if (keys.size === 0) this.#tagIndex.delete(tag);
|
|
384
|
+
for (const [key, entry] of [...this.#store]) {
|
|
385
|
+
if (key.startsWith(prefix)) this.#evict(key, entry);
|
|
226
386
|
}
|
|
227
387
|
}
|
|
228
388
|
|
|
@@ -252,15 +412,7 @@ export class MemoryDriver implements TaggableDriver {
|
|
|
252
412
|
for (const key of keys) toDelete.add(key);
|
|
253
413
|
}
|
|
254
414
|
}
|
|
255
|
-
for (const key of toDelete)
|
|
256
|
-
const entry = this.#store.get(key);
|
|
257
|
-
if (entry) {
|
|
258
|
-
for (const t of entry.tags) {
|
|
259
|
-
this.#tagIndex.get(t)?.delete(key);
|
|
260
|
-
}
|
|
261
|
-
}
|
|
262
|
-
this.#store.delete(key);
|
|
263
|
-
}
|
|
415
|
+
for (const key of toDelete) this.#deleteEntry(key);
|
|
264
416
|
for (const tag of tags) this.#tagIndex.delete(tag);
|
|
265
417
|
}
|
|
266
418
|
|