@c9up/echo 0.2.2 → 0.2.4

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.
Files changed (114) hide show
  1. package/dist/CacheManager.d.ts +2 -0
  2. package/dist/CacheManager.d.ts.map +1 -1
  3. package/dist/CacheManager.js +92 -32
  4. package/dist/CacheManager.js.map +1 -1
  5. package/dist/EchoProvider.d.ts.map +1 -1
  6. package/dist/EchoProvider.js +32 -3
  7. package/dist/EchoProvider.js.map +1 -1
  8. package/dist/StoreManager.d.ts +28 -9
  9. package/dist/StoreManager.d.ts.map +1 -1
  10. package/dist/StoreManager.js +42 -18
  11. package/dist/StoreManager.js.map +1 -1
  12. package/dist/bytes.d.ts +13 -0
  13. package/dist/bytes.d.ts.map +1 -0
  14. package/dist/bytes.js +35 -0
  15. package/dist/bytes.js.map +1 -0
  16. package/dist/claim.d.ts +15 -0
  17. package/dist/claim.d.ts.map +1 -0
  18. package/dist/claim.js +10 -0
  19. package/dist/claim.js.map +1 -0
  20. package/dist/configure.d.ts +7 -0
  21. package/dist/configure.d.ts.map +1 -1
  22. package/dist/configure.js +5 -18
  23. package/dist/configure.js.map +1 -1
  24. package/dist/console/cacheClear.d.ts +13 -0
  25. package/dist/console/cacheClear.d.ts.map +1 -0
  26. package/dist/console/cacheClear.js +69 -0
  27. package/dist/console/cacheClear.js.map +1 -0
  28. package/dist/console/cacheDelete.d.ts +11 -0
  29. package/dist/console/cacheDelete.d.ts.map +1 -0
  30. package/dist/console/cacheDelete.js +42 -0
  31. package/dist/console/cacheDelete.js.map +1 -0
  32. package/dist/console/cachePrune.d.ts +9 -0
  33. package/dist/console/cachePrune.d.ts.map +1 -0
  34. package/dist/console/cachePrune.js +35 -0
  35. package/dist/console/cachePrune.js.map +1 -0
  36. package/dist/console/contract.d.ts +64 -0
  37. package/dist/console/contract.d.ts.map +1 -0
  38. package/dist/console/contract.js +32 -0
  39. package/dist/console/contract.js.map +1 -0
  40. package/dist/console/index.d.ts +25 -0
  41. package/dist/console/index.d.ts.map +1 -0
  42. package/dist/console/index.js +38 -0
  43. package/dist/console/index.js.map +1 -0
  44. package/dist/console/store.d.ts +14 -0
  45. package/dist/console/store.d.ts.map +1 -0
  46. package/dist/console/store.js +35 -0
  47. package/dist/console/store.js.map +1 -0
  48. package/dist/drivers/MemoryDriver.d.ts +36 -1
  49. package/dist/drivers/MemoryDriver.d.ts.map +1 -1
  50. package/dist/drivers/MemoryDriver.js +157 -62
  51. package/dist/drivers/MemoryDriver.js.map +1 -1
  52. package/dist/drivers/RedisDriver.d.ts +13 -8
  53. package/dist/drivers/RedisDriver.d.ts.map +1 -1
  54. package/dist/drivers/RedisDriver.js +171 -94
  55. package/dist/drivers/RedisDriver.js.map +1 -1
  56. package/dist/drivers/TieredDriver.d.ts +42 -0
  57. package/dist/drivers/TieredDriver.d.ts.map +1 -1
  58. package/dist/drivers/TieredDriver.js +114 -9
  59. package/dist/drivers/TieredDriver.js.map +1 -1
  60. package/dist/duration.d.ts +13 -3
  61. package/dist/duration.d.ts.map +1 -1
  62. package/dist/duration.js +22 -7
  63. package/dist/duration.js.map +1 -1
  64. package/dist/errors.d.ts +60 -2
  65. package/dist/errors.d.ts.map +1 -1
  66. package/dist/errors.js +81 -6
  67. package/dist/errors.js.map +1 -1
  68. package/dist/index.d.ts +4 -4
  69. package/dist/index.d.ts.map +1 -1
  70. package/dist/index.js +3 -3
  71. package/dist/index.js.map +1 -1
  72. package/dist/quasar.d.ts +1 -1
  73. package/dist/quasar.d.ts.map +1 -1
  74. package/dist/quasar.js +27 -6
  75. package/dist/quasar.js.map +1 -1
  76. package/dist/services/main.d.ts +1 -1
  77. package/dist/services/main.d.ts.map +1 -1
  78. package/dist/services/main.js +22 -5
  79. package/dist/services/main.js.map +1 -1
  80. package/dist/stubs.d.ts +14 -0
  81. package/dist/stubs.d.ts.map +1 -0
  82. package/dist/stubs.js +15 -0
  83. package/dist/stubs.js.map +1 -0
  84. package/dist/types.d.ts +12 -1
  85. package/dist/types.d.ts.map +1 -1
  86. package/dist/vendor/quasarConnection.d.ts +26 -3
  87. package/dist/vendor/quasarConnection.d.ts.map +1 -1
  88. package/dist/vendor/quasarConnection.js +44 -23
  89. package/dist/vendor/quasarConnection.js.map +1 -1
  90. package/package.json +8 -3
  91. package/src/CacheManager.ts +117 -41
  92. package/src/EchoProvider.ts +45 -4
  93. package/src/StoreManager.ts +86 -31
  94. package/src/bytes.ts +38 -0
  95. package/src/claim.ts +22 -0
  96. package/src/configure.ts +13 -21
  97. package/src/console/cacheClear.ts +96 -0
  98. package/src/console/cacheDelete.ts +65 -0
  99. package/src/console/cachePrune.ts +57 -0
  100. package/src/console/contract.ts +93 -0
  101. package/src/console/index.ts +61 -0
  102. package/src/console/store.ts +47 -0
  103. package/src/drivers/MemoryDriver.ts +205 -60
  104. package/src/drivers/RedisDriver.ts +205 -101
  105. package/src/drivers/TieredDriver.ts +169 -9
  106. package/src/duration.ts +28 -7
  107. package/src/errors.ts +103 -6
  108. package/src/index.ts +17 -3
  109. package/src/quasar.ts +44 -8
  110. package/src/services/main.ts +26 -8
  111. package/src/stubs.ts +16 -0
  112. package/src/types.ts +13 -2
  113. package/src/vendor/quasarConnection.ts +84 -22
  114. package/stubs/config/cache.stub +21 -0
@@ -0,0 +1,96 @@
1
+ /**
2
+ * `cache:clear` — empty a store, one of its namespaces, or its entries under
3
+ * some tags.
4
+ *
5
+ * ream cache:clear
6
+ * ream cache:clear redis --namespace=users
7
+ * ream cache:clear --tags=products --tags=shop
8
+ *
9
+ * In production it asks first, unless `--force`.
10
+ */
11
+
12
+ import {
13
+ argument,
14
+ type CommandApp,
15
+ type CommandLogger,
16
+ type CommandPrompt,
17
+ type EchoCommandClass,
18
+ flag,
19
+ } from "./contract.js";
20
+ import { consent, resolveStore } from "./store.js";
21
+
22
+ export function cacheClearCommand(): EchoCommandClass {
23
+ return class CacheClear {
24
+ static commandName = "cache:clear";
25
+ static description = "Clear the application cache";
26
+ static options = { startApp: true };
27
+ static args = [
28
+ argument("store", {
29
+ description: "Define a custom cache store to clear",
30
+ required: false,
31
+ }),
32
+ ];
33
+ static flags = [
34
+ flag("namespace", "string", {
35
+ description: "Select a cache namespace to clear",
36
+ alias: ["n"],
37
+ }),
38
+ flag("tags", "array", {
39
+ description: "Specify tags to invalidate",
40
+ alias: ["t"],
41
+ }),
42
+ flag("force", "boolean", {
43
+ description: "Explicitly force to clear cache in production",
44
+ }),
45
+ ];
46
+
47
+ declare store?: string;
48
+ declare namespace?: string;
49
+ declare tags?: string[];
50
+ declare force?: boolean;
51
+ declare logger: CommandLogger;
52
+ declare prompt: CommandPrompt;
53
+ declare app: CommandApp;
54
+ declare exitCode?: number;
55
+
56
+ async run(): Promise<void> {
57
+ const cache = resolveStore(this.store, this.logger);
58
+ if (cache === undefined) {
59
+ this.exitCode = 1;
60
+ return;
61
+ }
62
+ const tags = this.tags ?? [];
63
+ if (this.namespace && tags.length > 0) {
64
+ this.logger.error(
65
+ "Cannot use --namespace and --tags options together. Please choose one or the other.",
66
+ );
67
+ this.exitCode = 1;
68
+ return;
69
+ }
70
+ if (
71
+ this.app.inProduction &&
72
+ !this.force &&
73
+ !(await consent(
74
+ this.prompt,
75
+ "You are in production environment. Want to continue clearing the cache?",
76
+ ))
77
+ ) {
78
+ return;
79
+ }
80
+ if (tags.length > 0) {
81
+ await cache.deleteByTag({ tags });
82
+ this.logger.success(
83
+ `Invalidated tags [${tags.join(", ")}] for "${cache.name}" cache successfully`,
84
+ );
85
+ } else if (this.namespace) {
86
+ await cache.namespace(this.namespace).clear();
87
+ this.logger.success(
88
+ `Cleared namespace "${this.namespace}" for "${cache.name}" cache successfully`,
89
+ );
90
+ } else {
91
+ await cache.clear();
92
+ this.logger.success(`Cleared "${cache.name}" cache successfully`);
93
+ }
94
+ }
95
+ };
96
+ }
@@ -0,0 +1,65 @@
1
+ /**
2
+ * `cache:delete` — remove one key from a store.
3
+ *
4
+ * ream cache:delete user:42
5
+ * ream cache:delete user:42 redis
6
+ *
7
+ * In production it asks first.
8
+ */
9
+
10
+ import {
11
+ argument,
12
+ type CommandApp,
13
+ type CommandLogger,
14
+ type CommandPrompt,
15
+ type EchoCommandClass,
16
+ } from "./contract.js";
17
+ import { consent, resolveStore } from "./store.js";
18
+
19
+ export function cacheDeleteCommand(): EchoCommandClass {
20
+ return class CacheDelete {
21
+ static commandName = "cache:delete";
22
+ static description = "Delete a specific cache entry by key";
23
+ static options = { startApp: true };
24
+ static args = [
25
+ argument("key", { description: "The cache key to delete" }),
26
+ argument("store", {
27
+ description: "Define a custom cache store to delete from",
28
+ required: false,
29
+ }),
30
+ ];
31
+
32
+ declare key: string;
33
+ declare store?: string;
34
+ declare logger: CommandLogger;
35
+ declare prompt: CommandPrompt;
36
+ declare app: CommandApp;
37
+ declare exitCode?: number;
38
+
39
+ async run(): Promise<void> {
40
+ const cache = resolveStore(this.store, this.logger);
41
+ if (cache === undefined) {
42
+ this.exitCode = 1;
43
+ return;
44
+ }
45
+ if (
46
+ this.app.inProduction &&
47
+ !(await consent(
48
+ this.prompt,
49
+ `You are in production environment. Want to continue deleting cache key "${this.key}"?`,
50
+ ))
51
+ ) {
52
+ return;
53
+ }
54
+ if (await cache.delete({ key: this.key })) {
55
+ this.logger.success(
56
+ `Deleted cache key "${this.key}" from "${cache.name}" cache successfully`,
57
+ );
58
+ } else {
59
+ this.logger.warning(
60
+ `Cache key "${this.key}" not found in "${cache.name}" cache`,
61
+ );
62
+ }
63
+ }
64
+ };
65
+ }
@@ -0,0 +1,57 @@
1
+ /**
2
+ * `cache:prune` — drop the entries a store knows to be expired. Only useful
3
+ * for stores that do not expire on their own; Redis does.
4
+ *
5
+ * In production it asks first.
6
+ */
7
+
8
+ import {
9
+ argument,
10
+ type CommandApp,
11
+ type CommandLogger,
12
+ type CommandPrompt,
13
+ type EchoCommandClass,
14
+ } from "./contract.js";
15
+ import { consent, resolveStore } from "./store.js";
16
+
17
+ export function cachePruneCommand(): EchoCommandClass {
18
+ return class CachePrune {
19
+ static commandName = "cache:prune";
20
+ static description =
21
+ "Remove expired cache entries from the selected store. This command is only useful for stores without native TTL support.";
22
+ static options = { startApp: true };
23
+ static args = [
24
+ argument("store", {
25
+ description: "Define a custom cache store to prune",
26
+ required: false,
27
+ }),
28
+ ];
29
+
30
+ declare store?: string;
31
+ declare logger: CommandLogger;
32
+ declare prompt: CommandPrompt;
33
+ declare app: CommandApp;
34
+ declare exitCode?: number;
35
+
36
+ async run(): Promise<void> {
37
+ const cache = resolveStore(this.store, this.logger);
38
+ if (cache === undefined) {
39
+ this.exitCode = 1;
40
+ return;
41
+ }
42
+ if (
43
+ this.app.inProduction &&
44
+ !(await consent(
45
+ this.prompt,
46
+ "You are in production environment. Want to continue pruning expired cache entries?",
47
+ ))
48
+ ) {
49
+ return;
50
+ }
51
+ await cache.prune();
52
+ this.logger.success(
53
+ `Pruned expired entries from "${cache.name}" cache successfully`,
54
+ );
55
+ }
56
+ };
57
+ }
@@ -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
+ }