@alicesystems/cli 0.1.0-alpha.2 → 0.1.0-alpha.3
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 +6 -0
- package/dist/add-db.d.ts +1 -0
- package/dist/add-db.js +12 -2
- package/dist/add-input.d.ts +117 -0
- package/dist/add-input.js +137 -0
- package/dist/add-json.d.ts +3 -0
- package/dist/add-json.js +61 -0
- package/dist/add-shared-package.js +16 -2
- package/dist/alice-record-update.d.ts +20 -0
- package/dist/alice-record-update.js +127 -0
- package/dist/application-integration.js +22 -4
- package/dist/index.js +48 -4
- package/dist/init-input.d.ts +30 -0
- package/dist/init-input.js +48 -0
- package/dist/init.d.ts +2 -0
- package/dist/init.js +45 -1
- package/dist/templates/database/mysql/docker-compose.yml +20 -0
- package/dist/templates/database/postgres/docker-compose.yml +20 -0
- package/dist/templates/project/alice.json.tpl +1 -0
- package/dist/templates/project/apps/mobile/README.md.tpl +8 -0
- package/dist/templates/project/apps/mobile/css.d.ts +1 -0
- package/dist/templates/project/apps/mobile/global.css +6 -0
- package/dist/templates/project/apps/mobile/metro.config.js +4 -0
- package/dist/templates/project/apps/mobile/nativewind-env.d.ts +3 -0
- package/dist/templates/project/apps/mobile/package.json.tpl +9 -0
- package/dist/templates/project/apps/mobile/postcss.config.mjs +5 -0
- package/dist/templates/project/apps/mobile/{app → src/app}/_layout.tsx +1 -0
- package/dist/templates/project/apps/mobile/src/app/index.tsx.tpl +61 -0
- package/dist/templates/project/apps/mobile/tsconfig.json.tpl +1 -1
- package/dist/templates/project/oxlint.config.mts.tpl +2 -0
- package/dist/templates/project/packages/user-interface/README.md.tpl +3 -2
- package/dist/templates/project/packages/user-interface/package.json.tpl +1 -0
- package/dist/templates/project/packages/user-interface/src/styles/native.css +72 -0
- package/dist/templates/project/packages/user-interface/tests/user-interface.test.tsx +14 -0
- package/dist/templates/project/pnpm-workspace.yaml.tpl +4 -0
- package/node_modules/@alice/core/dist/alice-record.d.ts +139 -0
- package/node_modules/@alice/core/dist/alice-record.js +215 -0
- package/node_modules/@alice/core/dist/database-recipe.d.ts +12 -0
- package/node_modules/@alice/core/dist/database-recipe.js +8 -0
- package/node_modules/@alice/core/dist/index.d.ts +2 -0
- package/node_modules/@alice/core/dist/index.js +1 -0
- package/node_modules/@alice/core/dist/project-init.js +53 -18
- package/package.json +1 -1
- package/dist/templates/project/apps/mobile/app/index.tsx.tpl +0 -90
- package/dist/templates/project/packages/cache/README.md.tpl +0 -42
- package/dist/templates/project/packages/cache/package.json.tpl +0 -26
- package/dist/templates/project/packages/cache/src/cache.ts +0 -50
- package/dist/templates/project/packages/cache/src/create-cache.ts +0 -16
- package/dist/templates/project/packages/cache/src/index.ts +0 -4
- package/dist/templates/project/packages/cache/src/memory-cache.ts +0 -147
- package/dist/templates/project/packages/cache/tests/cache.test.mjs +0 -83
- package/dist/templates/project/packages/cache/tsconfig.json.tpl +0 -1
- package/dist/templates/project/packages/errors/src/app-error.ts +0 -31
- package/dist/templates/project/packages/errors/src/codes.ts +0 -29
- package/dist/templates/project/packages/errors/src/response.ts +0 -46
- package/dist/templates/project/packages/observability/README.md.tpl +0 -30
- package/dist/templates/project/packages/observability/package.json.tpl +0 -26
- package/dist/templates/project/packages/observability/src/error-reporting.ts +0 -23
- package/dist/templates/project/packages/observability/src/index.ts +0 -13
- package/dist/templates/project/packages/observability/src/logger.ts +0 -123
- package/dist/templates/project/packages/observability/src/tracing.ts +0 -41
- package/dist/templates/project/packages/observability/tests/observability.test.mjs +0 -92
- package/dist/templates/project/packages/observability/tsconfig.json.tpl +0 -1
- package/dist/templates/project/packages/user-interface/src/index.ts +0 -2
- package/dist/templates/project/packages/user-interface/src/web/button.tsx +0 -33
- package/dist/templates/project/packages/user-interface/src/web/card.tsx +0 -13
- package/dist/templates/project/packages/user-interface/src/web/cn.ts +0 -6
- package/dist/templates/project/packages/user-interface/src/web/index.ts +0 -4
- package/dist/templates/project/packages/user-interface/tests/user-interface.test.mjs +0 -49
- package/dist/templates/project/packages/user-interface/theme.css +0 -37
|
@@ -1,42 +0,0 @@
|
|
|
1
|
-
# @alice/cache
|
|
2
|
-
|
|
3
|
-
## Purpose
|
|
4
|
-
|
|
5
|
-
One shared cache with a small key-value API: sessions, one-time tokens and rate-limit counters. Today it is process-local; a Redis adapter will keep the same API.
|
|
6
|
-
|
|
7
|
-
## Tier
|
|
8
|
-
|
|
9
|
-
Infrastructure. May import foundation packages only. (This starter implementation imports none.)
|
|
10
|
-
|
|
11
|
-
## Exports
|
|
12
|
-
|
|
13
|
-
- `.` (`src/index.ts`):
|
|
14
|
-
- `createCache({ keyPrefix, onError?, url? })`: the setup function. The app calls it once at startup and passes the result to whatever needs a cache. Passing a `url` throws, because a networked cache is **not implemented**; it is never silently replaced by memory.
|
|
15
|
-
- `Cache`: what it returns:
|
|
16
|
-
- `get(key)`: the value, or `null` if the key is missing or has expired;
|
|
17
|
-
- `set(key, value, ttlSeconds?)`: stores a string. With `ttlSeconds` (a whole number, 1 or more) it is deleted after that many seconds;
|
|
18
|
-
- `getAndDelete(key)`: reads a value and deletes it in one step, so it can only be used once. `null` if missing;
|
|
19
|
-
- `increment(key, ttlSeconds)`: adds 1 to a counter and returns the new value. A new counter starts at 1 and expires `ttlSeconds` after it was created; later increments never extend that;
|
|
20
|
-
- `delete(key)`: removes a key (a missing key is fine);
|
|
21
|
-
- `ping()`: resolves when the cache answers, rejects when it does not, for `/health`;
|
|
22
|
-
- `close()`: releases the cache on shutdown; later commands reject.
|
|
23
|
-
- `createMemoryCache({ keyPrefix?, maxEntries?, now? })`: the process-local implementation behind `createCache`, with least-recently-used eviction and a clock override for tests.
|
|
24
|
-
- `CreateCacheOptions`, `MemoryCacheOptions`: the options types.
|
|
25
|
-
|
|
26
|
-
`keyPrefix` is required so two projects sharing one store can never clash. `onError` is accepted so callers do not change when a networked adapter arrives; the memory cache has no connection, so it never calls it. The package never logs: the app decides what to write down.
|
|
27
|
-
|
|
28
|
-
## Environment keys
|
|
29
|
-
|
|
30
|
-
None. The memory cache needs no configuration. The Redis adapter will add a `./keys` export (`REDIS_URL`) that the app composes with `extends` and passes in; the package itself will never read the environment.
|
|
31
|
-
|
|
32
|
-
## Using it
|
|
33
|
-
|
|
34
|
-
```ts
|
|
35
|
-
import { createCache } from "@alice/cache";
|
|
36
|
-
|
|
37
|
-
const cache = createCache({
|
|
38
|
-
keyPrefix: "acme:",
|
|
39
|
-
onError: (error) => logger.error("Cache connection error", { error }),
|
|
40
|
-
});
|
|
41
|
-
await cache.set("session:1", JSON.stringify(session), 3600);
|
|
42
|
-
```
|
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@alice/cache",
|
|
3
|
-
"version": "0.1.0",
|
|
4
|
-
"private": true,
|
|
5
|
-
"description": "Cache abstraction with an in-memory adapter.",
|
|
6
|
-
"type": "module",
|
|
7
|
-
"exports": {
|
|
8
|
-
".": {
|
|
9
|
-
"types": "./dist/index.d.ts",
|
|
10
|
-
"import": "./dist/index.js"
|
|
11
|
-
}
|
|
12
|
-
},
|
|
13
|
-
"scripts": {
|
|
14
|
-
"build": "tsc -p tsconfig.json",
|
|
15
|
-
"types:check": "tsc -p tsconfig.json --noEmit",
|
|
16
|
-
"test": "node --test tests/*.test.mjs"
|
|
17
|
-
},
|
|
18
|
-
"devDependencies": {
|
|
19
|
-
"@alice/typescript": "workspace:*",
|
|
20
|
-
"@types/node": "24.19.2",
|
|
21
|
-
"typescript": "6.0.3"
|
|
22
|
-
},
|
|
23
|
-
"engines": {
|
|
24
|
-
"node": ">=24 <25"
|
|
25
|
-
}
|
|
26
|
-
}
|
|
@@ -1,50 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* What `createCache` returns. Values are strings (serialise your own JSON). The shape follows
|
|
3
|
-
* the Redis-backed cache this package will gain, so callers do not change when it arrives.
|
|
4
|
-
*/
|
|
5
|
-
export interface Cache {
|
|
6
|
-
/** The stored value, or `null` if the key is missing or has expired. */
|
|
7
|
-
readonly get: (key: string) => Promise<string | null>;
|
|
8
|
-
/** Stores a value. With `ttlSeconds`, it is deleted by itself after that many seconds. */
|
|
9
|
-
readonly set: (
|
|
10
|
-
key: string,
|
|
11
|
-
value: string,
|
|
12
|
-
ttlSeconds?: number
|
|
13
|
-
) => Promise<void>;
|
|
14
|
-
/**
|
|
15
|
-
* Reads a value and deletes it in one step, so it can only be used once (for example a
|
|
16
|
-
* one-time token). `null` if the key is missing.
|
|
17
|
-
*/
|
|
18
|
-
readonly getAndDelete: (key: string) => Promise<string | null>;
|
|
19
|
-
/**
|
|
20
|
-
* Adds 1 to the counter at `key` and returns the new value (used for rate limits). A new
|
|
21
|
-
* counter starts at 1 and expires `ttlSeconds` after it was created; later increments
|
|
22
|
-
* never extend that.
|
|
23
|
-
*/
|
|
24
|
-
readonly increment: (key: string, ttlSeconds: number) => Promise<number>;
|
|
25
|
-
/** Removes a key. Removing a key that does not exist is not an error. */
|
|
26
|
-
readonly delete: (key: string) => Promise<void>;
|
|
27
|
-
/** Resolves when the cache answers, and rejects when it does not. For health checks. */
|
|
28
|
-
readonly ping: () => Promise<void>;
|
|
29
|
-
/** Releases the cache. The app calls it on shutdown; later commands reject. */
|
|
30
|
-
readonly close: () => Promise<void>;
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
export interface CreateCacheOptions {
|
|
34
|
-
/**
|
|
35
|
-
* Put in front of every key (for example `acme:`), so two projects sharing one store can
|
|
36
|
-
* never read or overwrite each other's keys. Required so the choice is deliberate.
|
|
37
|
-
*/
|
|
38
|
-
readonly keyPrefix: string;
|
|
39
|
-
/**
|
|
40
|
-
* Called when the connection fails or drops, so the app can log it; the package never logs.
|
|
41
|
-
* The memory cache has no connection, so it never calls this. It exists so callers do not
|
|
42
|
-
* change when a networked adapter replaces the memory cache.
|
|
43
|
-
*/
|
|
44
|
-
readonly onError?: (error: Error) => void;
|
|
45
|
-
/**
|
|
46
|
-
* Connection URL for a networked cache. **Not implemented yet**: passing one throws rather
|
|
47
|
-
* than quietly using memory.
|
|
48
|
-
*/
|
|
49
|
-
readonly url?: string;
|
|
50
|
-
}
|
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
import type { Cache, CreateCacheOptions } from "./cache.js";
|
|
2
|
-
import { createMemoryCache } from "./memory-cache.js";
|
|
3
|
-
|
|
4
|
-
/**
|
|
5
|
-
* The one setup function for this package. The app calls it once at startup and passes the
|
|
6
|
-
* result to whatever needs a cache. It returns a process-local cache; a Redis adapter is not
|
|
7
|
-
* implemented, so a `url` is rejected.
|
|
8
|
-
*/
|
|
9
|
-
export function createCache(options: CreateCacheOptions): Cache {
|
|
10
|
-
if (options.url !== undefined) {
|
|
11
|
-
throw new Error(
|
|
12
|
-
"A networked cache is not implemented: remove `url` to use the in-memory cache, or provide your own Cache."
|
|
13
|
-
);
|
|
14
|
-
}
|
|
15
|
-
return createMemoryCache({ keyPrefix: options.keyPrefix });
|
|
16
|
-
}
|
|
@@ -1,147 +0,0 @@
|
|
|
1
|
-
import type { Cache } from "./cache.js";
|
|
2
|
-
|
|
3
|
-
export interface MemoryCacheOptions {
|
|
4
|
-
/** Put in front of every key. Defaults to none. */
|
|
5
|
-
readonly keyPrefix?: string;
|
|
6
|
-
/** Least-recently-used entries are evicted beyond this size. Defaults to 1000. */
|
|
7
|
-
readonly maxEntries?: number;
|
|
8
|
-
/** Clock override for tests, in milliseconds. */
|
|
9
|
-
readonly now?: () => number;
|
|
10
|
-
}
|
|
11
|
-
|
|
12
|
-
interface Entry {
|
|
13
|
-
readonly value: string;
|
|
14
|
-
readonly expiresAt: number | undefined;
|
|
15
|
-
}
|
|
16
|
-
|
|
17
|
-
const millisecondsPerSecond = 1000;
|
|
18
|
-
|
|
19
|
-
/** Interface methods return promises, so invalid input must reject rather than throw. */
|
|
20
|
-
function settle<Result>(operation: () => Result): Promise<Result> {
|
|
21
|
-
try {
|
|
22
|
-
return Promise.resolve(operation());
|
|
23
|
-
} catch (error) {
|
|
24
|
-
return Promise.reject(error);
|
|
25
|
-
}
|
|
26
|
-
}
|
|
27
|
-
|
|
28
|
-
/** Fails early with a clear message, as a networked cache would reject an expiry of zero. */
|
|
29
|
-
function assertTtl(ttlSeconds: number): void {
|
|
30
|
-
if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1) {
|
|
31
|
-
throw new TypeError(
|
|
32
|
-
`ttlSeconds must be a whole number of seconds, 1 or more (got ${ttlSeconds})`
|
|
33
|
-
);
|
|
34
|
-
}
|
|
35
|
-
}
|
|
36
|
-
|
|
37
|
-
/** Process-local cache for tests and single-process use. Not shared across instances or restarts. */
|
|
38
|
-
export function createMemoryCache(options: MemoryCacheOptions = {}): Cache {
|
|
39
|
-
const maxEntries = options.maxEntries ?? 1000;
|
|
40
|
-
const prefix = options.keyPrefix ?? "";
|
|
41
|
-
const now = options.now ?? Date.now;
|
|
42
|
-
if (!Number.isInteger(maxEntries) || maxEntries < 1) {
|
|
43
|
-
throw new TypeError("maxEntries must be a positive integer.");
|
|
44
|
-
}
|
|
45
|
-
const entries = new Map<string, Entry>();
|
|
46
|
-
let closed = false;
|
|
47
|
-
|
|
48
|
-
function qualify(key: string): string {
|
|
49
|
-
if (closed) {
|
|
50
|
-
throw new Error("The cache is closed.");
|
|
51
|
-
}
|
|
52
|
-
if (typeof key !== "string" || key.length === 0) {
|
|
53
|
-
throw new TypeError("Cache keys must be non-empty strings.");
|
|
54
|
-
}
|
|
55
|
-
return `${prefix}${key}`;
|
|
56
|
-
}
|
|
57
|
-
function read(key: string): Entry | undefined {
|
|
58
|
-
const entry = entries.get(key);
|
|
59
|
-
if (entry === undefined) {
|
|
60
|
-
return undefined;
|
|
61
|
-
}
|
|
62
|
-
if (entry.expiresAt !== undefined && entry.expiresAt <= now()) {
|
|
63
|
-
entries.delete(key);
|
|
64
|
-
return undefined;
|
|
65
|
-
}
|
|
66
|
-
// Refresh recency.
|
|
67
|
-
entries.delete(key);
|
|
68
|
-
entries.set(key, entry);
|
|
69
|
-
return entry;
|
|
70
|
-
}
|
|
71
|
-
function write(key: string, value: string, ttlSeconds?: number): void {
|
|
72
|
-
entries.delete(key);
|
|
73
|
-
entries.set(key, {
|
|
74
|
-
expiresAt:
|
|
75
|
-
ttlSeconds === undefined
|
|
76
|
-
? undefined
|
|
77
|
-
: now() + ttlSeconds * millisecondsPerSecond,
|
|
78
|
-
value,
|
|
79
|
-
});
|
|
80
|
-
while (entries.size > maxEntries) {
|
|
81
|
-
const oldest = entries.keys().next().value;
|
|
82
|
-
if (oldest === undefined) {
|
|
83
|
-
break;
|
|
84
|
-
}
|
|
85
|
-
entries.delete(oldest);
|
|
86
|
-
}
|
|
87
|
-
}
|
|
88
|
-
|
|
89
|
-
return {
|
|
90
|
-
close: () =>
|
|
91
|
-
settle(() => {
|
|
92
|
-
closed = true;
|
|
93
|
-
entries.clear();
|
|
94
|
-
}),
|
|
95
|
-
delete: (key) =>
|
|
96
|
-
settle(() => {
|
|
97
|
-
entries.delete(qualify(key));
|
|
98
|
-
}),
|
|
99
|
-
get: (key) => settle(() => read(qualify(key))?.value ?? null),
|
|
100
|
-
getAndDelete: (key) =>
|
|
101
|
-
settle(() => {
|
|
102
|
-
const qualified = qualify(key);
|
|
103
|
-
const entry = read(qualified);
|
|
104
|
-
entries.delete(qualified);
|
|
105
|
-
return entry?.value ?? null;
|
|
106
|
-
}),
|
|
107
|
-
increment: (key, ttlSeconds) =>
|
|
108
|
-
settle(() => {
|
|
109
|
-
const qualified = qualify(key);
|
|
110
|
-
assertTtl(ttlSeconds);
|
|
111
|
-
const entry = read(qualified);
|
|
112
|
-
if (entry === undefined) {
|
|
113
|
-
write(qualified, "1", ttlSeconds);
|
|
114
|
-
return 1;
|
|
115
|
-
}
|
|
116
|
-
const count = Number(entry.value);
|
|
117
|
-
if (!Number.isInteger(count)) {
|
|
118
|
-
throw new TypeError(`The value at ${key} is not a counter.`);
|
|
119
|
-
}
|
|
120
|
-
// Later increments never extend the expiry set when the counter was created.
|
|
121
|
-
entries.set(qualified, {
|
|
122
|
-
expiresAt: entry.expiresAt,
|
|
123
|
-
value: String(count + 1),
|
|
124
|
-
});
|
|
125
|
-
return count + 1;
|
|
126
|
-
}),
|
|
127
|
-
ping: () =>
|
|
128
|
-
settle(() => {
|
|
129
|
-
if (closed) {
|
|
130
|
-
throw new Error("The cache is closed.");
|
|
131
|
-
}
|
|
132
|
-
}),
|
|
133
|
-
set: (key, value, ttlSeconds) =>
|
|
134
|
-
settle(() => {
|
|
135
|
-
const qualified = qualify(key);
|
|
136
|
-
if (typeof value !== "string") {
|
|
137
|
-
throw new TypeError(
|
|
138
|
-
"Cache values must be strings; serialise objects yourself."
|
|
139
|
-
);
|
|
140
|
-
}
|
|
141
|
-
if (ttlSeconds !== undefined) {
|
|
142
|
-
assertTtl(ttlSeconds);
|
|
143
|
-
}
|
|
144
|
-
write(qualified, value, ttlSeconds);
|
|
145
|
-
}),
|
|
146
|
-
};
|
|
147
|
-
}
|
|
@@ -1,83 +0,0 @@
|
|
|
1
|
-
/* oxlint-disable no-await-in-loop -- each invalid ttl is checked in turn */
|
|
2
|
-
import assert from "node:assert/strict";
|
|
3
|
-
import test from "node:test";
|
|
4
|
-
|
|
5
|
-
import { createCache, createMemoryCache } from "../dist/index.js";
|
|
6
|
-
|
|
7
|
-
test("stores, reads and deletes string values", async () => {
|
|
8
|
-
const cache = createCache({ keyPrefix: "acme:" });
|
|
9
|
-
await cache.set("a", "one");
|
|
10
|
-
assert.equal(await cache.get("a"), "one");
|
|
11
|
-
assert.equal(await cache.get("missing"), null);
|
|
12
|
-
await cache.delete("a");
|
|
13
|
-
assert.equal(await cache.get("a"), null);
|
|
14
|
-
await cache.delete("a");
|
|
15
|
-
});
|
|
16
|
-
test("getAndDelete reads a value once", async () => {
|
|
17
|
-
const cache = createMemoryCache();
|
|
18
|
-
await cache.set("token", "abc");
|
|
19
|
-
assert.equal(await cache.getAndDelete("token"), "abc");
|
|
20
|
-
assert.equal(await cache.getAndDelete("token"), null);
|
|
21
|
-
});
|
|
22
|
-
test("entries expire after ttlSeconds", async () => {
|
|
23
|
-
let time = 1000;
|
|
24
|
-
const cache = createMemoryCache({ now: () => time });
|
|
25
|
-
await cache.set("a", "1", 5);
|
|
26
|
-
time += 4999;
|
|
27
|
-
assert.equal(await cache.get("a"), "1");
|
|
28
|
-
time += 1;
|
|
29
|
-
assert.equal(await cache.get("a"), null);
|
|
30
|
-
});
|
|
31
|
-
test("increment starts at 1 and never extends the expiry", async () => {
|
|
32
|
-
let time = 0;
|
|
33
|
-
const cache = createMemoryCache({ now: () => time });
|
|
34
|
-
assert.equal(await cache.increment("hits", 10), 1);
|
|
35
|
-
time += 6000;
|
|
36
|
-
assert.equal(await cache.increment("hits", 10), 2);
|
|
37
|
-
assert.equal(await cache.get("hits"), "2");
|
|
38
|
-
time += 4000;
|
|
39
|
-
assert.equal(await cache.get("hits"), null, "expiry counted from creation");
|
|
40
|
-
assert.equal(await cache.increment("hits", 10), 1);
|
|
41
|
-
});
|
|
42
|
-
test("key prefixes keep projects apart", async () => {
|
|
43
|
-
const a = createMemoryCache({ keyPrefix: "a:" });
|
|
44
|
-
await a.set("k", "v");
|
|
45
|
-
assert.equal(await a.get("k"), "v");
|
|
46
|
-
const b = createMemoryCache({ keyPrefix: "b:" });
|
|
47
|
-
assert.equal(await b.get("k"), null);
|
|
48
|
-
});
|
|
49
|
-
test("least recently used entries are evicted", async () => {
|
|
50
|
-
const cache = createMemoryCache({ maxEntries: 2 });
|
|
51
|
-
await cache.set("a", "1");
|
|
52
|
-
await cache.set("b", "2");
|
|
53
|
-
await cache.get("a");
|
|
54
|
-
await cache.set("c", "3");
|
|
55
|
-
assert.equal(await cache.get("b"), null);
|
|
56
|
-
assert.equal(await cache.get("a"), "1");
|
|
57
|
-
assert.equal(await cache.get("c"), "3");
|
|
58
|
-
});
|
|
59
|
-
test("ping works until the cache is closed", async () => {
|
|
60
|
-
const cache = createMemoryCache();
|
|
61
|
-
await cache.ping();
|
|
62
|
-
await cache.close();
|
|
63
|
-
await assert.rejects(cache.ping(), /closed/u);
|
|
64
|
-
await assert.rejects(cache.get("a"), /closed/u);
|
|
65
|
-
});
|
|
66
|
-
test("invalid input rejects", async () => {
|
|
67
|
-
const cache = createMemoryCache();
|
|
68
|
-
await assert.rejects(cache.get(""), /non-empty strings/u);
|
|
69
|
-
await assert.rejects(cache.set("a", 5), /must be strings/u);
|
|
70
|
-
for (const ttl of [0, -1, 1.5, Number.NaN]) {
|
|
71
|
-
await assert.rejects(cache.set("a", "1", ttl), /whole number of seconds/u);
|
|
72
|
-
await assert.rejects(cache.increment("a", ttl), /whole number of seconds/u);
|
|
73
|
-
}
|
|
74
|
-
await cache.set("text", "not a number");
|
|
75
|
-
await assert.rejects(cache.increment("text", 5), /not a counter/u);
|
|
76
|
-
assert.throws(() => createMemoryCache({ maxEntries: 0 }), /maxEntries/u);
|
|
77
|
-
});
|
|
78
|
-
test("a networked cache is not implemented and is never silently replaced", () => {
|
|
79
|
-
assert.throws(
|
|
80
|
-
() => createCache({ keyPrefix: "x:", url: "redis://localhost:6379" }),
|
|
81
|
-
/networked cache is not implemented/u
|
|
82
|
-
);
|
|
83
|
-
});
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{ "extends": "@alice/typescript/library.json" }
|
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
import { statusByCode } from "./codes.js";
|
|
2
|
-
import type { ErrorCode } from "./codes.js";
|
|
3
|
-
|
|
4
|
-
export interface AppErrorOptions {
|
|
5
|
-
readonly cause?: unknown;
|
|
6
|
-
/** Safe, serialisable context. Only sent to clients when `expose` is true. */
|
|
7
|
-
readonly details?: Readonly<Record<string, unknown>>;
|
|
8
|
-
/** Whether the message and details may be shown to an end user. Defaults to true for 4xx codes. */
|
|
9
|
-
readonly expose?: boolean;
|
|
10
|
-
}
|
|
11
|
-
|
|
12
|
-
/** The one error type applications and packages throw for expected failures. */
|
|
13
|
-
export class AppError extends Error {
|
|
14
|
-
readonly code: ErrorCode;
|
|
15
|
-
readonly status: number;
|
|
16
|
-
readonly details: Readonly<Record<string, unknown>> | undefined;
|
|
17
|
-
readonly expose: boolean;
|
|
18
|
-
|
|
19
|
-
constructor(code: ErrorCode, message: string, options: AppErrorOptions = {}) {
|
|
20
|
-
super(message, options.cause === undefined ? {} : { cause: options.cause });
|
|
21
|
-
this.name = "AppError";
|
|
22
|
-
this.code = code;
|
|
23
|
-
this.status = statusByCode[code];
|
|
24
|
-
this.details = options.details;
|
|
25
|
-
this.expose = options.expose ?? this.status < 500;
|
|
26
|
-
}
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
export function isAppError(value: unknown): value is AppError {
|
|
30
|
-
return value instanceof AppError;
|
|
31
|
-
}
|
|
@@ -1,29 +0,0 @@
|
|
|
1
|
-
/** Stable, machine-readable error codes. Add codes here; never reuse or rename one. */
|
|
2
|
-
export const errorCodes = {
|
|
3
|
-
badRequest: "BAD_REQUEST",
|
|
4
|
-
configuration: "CONFIGURATION_INVALID",
|
|
5
|
-
conflict: "CONFLICT",
|
|
6
|
-
forbidden: "FORBIDDEN",
|
|
7
|
-
internal: "INTERNAL",
|
|
8
|
-
notFound: "NOT_FOUND",
|
|
9
|
-
unauthenticated: "UNAUTHENTICATED",
|
|
10
|
-
unavailable: "SERVICE_UNAVAILABLE",
|
|
11
|
-
unsupported: "UNSUPPORTED",
|
|
12
|
-
validation: "VALIDATION_FAILED",
|
|
13
|
-
} as const;
|
|
14
|
-
|
|
15
|
-
export type ErrorCode = (typeof errorCodes)[keyof typeof errorCodes];
|
|
16
|
-
|
|
17
|
-
/** HTTP status each code maps to when an error crosses an HTTP boundary. */
|
|
18
|
-
export const statusByCode: Readonly<Record<ErrorCode, number>> = {
|
|
19
|
-
BAD_REQUEST: 400,
|
|
20
|
-
CONFIGURATION_INVALID: 500,
|
|
21
|
-
CONFLICT: 409,
|
|
22
|
-
FORBIDDEN: 403,
|
|
23
|
-
INTERNAL: 500,
|
|
24
|
-
NOT_FOUND: 404,
|
|
25
|
-
SERVICE_UNAVAILABLE: 503,
|
|
26
|
-
UNAUTHENTICATED: 401,
|
|
27
|
-
UNSUPPORTED: 501,
|
|
28
|
-
VALIDATION_FAILED: 422,
|
|
29
|
-
};
|
|
@@ -1,46 +0,0 @@
|
|
|
1
|
-
import { AppError } from "./app-error.js";
|
|
2
|
-
import { errorCodes } from "./codes.js";
|
|
3
|
-
import type { ErrorCode } from "./codes.js";
|
|
4
|
-
|
|
5
|
-
export interface ErrorBody {
|
|
6
|
-
readonly error: {
|
|
7
|
-
readonly code: ErrorCode;
|
|
8
|
-
readonly message: string;
|
|
9
|
-
readonly details?: Readonly<Record<string, unknown>>;
|
|
10
|
-
};
|
|
11
|
-
}
|
|
12
|
-
export interface ErrorResponse {
|
|
13
|
-
readonly status: number;
|
|
14
|
-
readonly body: ErrorBody;
|
|
15
|
-
}
|
|
16
|
-
|
|
17
|
-
const genericMessage = "An unexpected error occurred.";
|
|
18
|
-
|
|
19
|
-
/**
|
|
20
|
-
* Convert any thrown value into a client-safe response. Unknown errors, and AppErrors that are
|
|
21
|
-
* not marked `expose`, never leak their message, details, cause or stack.
|
|
22
|
-
*/
|
|
23
|
-
export function toErrorResponse(error: unknown): ErrorResponse {
|
|
24
|
-
if (error instanceof AppError) {
|
|
25
|
-
if (!error.expose) {
|
|
26
|
-
return {
|
|
27
|
-
body: { error: { code: error.code, message: genericMessage } },
|
|
28
|
-
status: error.status,
|
|
29
|
-
};
|
|
30
|
-
}
|
|
31
|
-
return {
|
|
32
|
-
body: {
|
|
33
|
-
error: {
|
|
34
|
-
code: error.code,
|
|
35
|
-
message: error.message,
|
|
36
|
-
...(error.details === undefined ? {} : { details: error.details }),
|
|
37
|
-
},
|
|
38
|
-
},
|
|
39
|
-
status: error.status,
|
|
40
|
-
};
|
|
41
|
-
}
|
|
42
|
-
return {
|
|
43
|
-
body: { error: { code: errorCodes.internal, message: genericMessage } },
|
|
44
|
-
status: 500,
|
|
45
|
-
};
|
|
46
|
-
}
|
|
@@ -1,30 +0,0 @@
|
|
|
1
|
-
# @alice/observability
|
|
2
|
-
|
|
3
|
-
## Purpose
|
|
4
|
-
|
|
5
|
-
Logging, error-reporting and tracing contracts. Portable; no runtime dependencies.
|
|
6
|
-
|
|
7
|
-
## Tier
|
|
8
|
-
|
|
9
|
-
Foundation. Imports no other internal package. Only the backend creates the logger; a package that needs to log is handed it (or a callback such as `onError`) as an argument.
|
|
10
|
-
|
|
11
|
-
## Exports
|
|
12
|
-
|
|
13
|
-
| Capability | Status |
|
|
14
|
-
| --- | --- |
|
|
15
|
-
| `createLogger({ level, sink, fields, redact })` | Implemented: structured records, child loggers, automatic redaction of fields such as `password`, `token`, `secret`, `cookie`. Default sink prints JSON lines. |
|
|
16
|
-
| `ErrorReporter` / `createLoggerErrorReporter(logger)` | Contract plus a reporter that logs. **No hosted error-tracking service is integrated.** |
|
|
17
|
-
| `Tracer` / `withSpan` | Contract plus helper. **Tracing is not implemented:** `inactiveTracer` records nothing and is named so. |
|
|
18
|
-
|
|
19
|
-
```ts
|
|
20
|
-
import { createLogger } from "@alice/observability";
|
|
21
|
-
|
|
22
|
-
const logger = createLogger({ level: "info", fields: { service: "backend" } });
|
|
23
|
-
logger.info("listening", { port: 3001 });
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
Creating a logger writes nothing and contacts nothing; the application decides when and where.
|
|
27
|
-
|
|
28
|
-
## Environment keys
|
|
29
|
-
|
|
30
|
-
None. The backend reads `LOG_LEVEL` in its own `src/keys.ts` and passes it to `createLogger`.
|
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@alice/observability",
|
|
3
|
-
"version": "0.1.0",
|
|
4
|
-
"private": true,
|
|
5
|
-
"description": "Structured logging, error reporting and tracing contracts.",
|
|
6
|
-
"type": "module",
|
|
7
|
-
"exports": {
|
|
8
|
-
".": {
|
|
9
|
-
"types": "./dist/index.d.ts",
|
|
10
|
-
"import": "./dist/index.js"
|
|
11
|
-
}
|
|
12
|
-
},
|
|
13
|
-
"scripts": {
|
|
14
|
-
"build": "tsc -p tsconfig.json",
|
|
15
|
-
"types:check": "tsc -p tsconfig.json --noEmit",
|
|
16
|
-
"test": "node --test tests/*.test.mjs"
|
|
17
|
-
},
|
|
18
|
-
"devDependencies": {
|
|
19
|
-
"@alice/typescript": "workspace:*",
|
|
20
|
-
"@types/node": "24.19.2",
|
|
21
|
-
"typescript": "6.0.3"
|
|
22
|
-
},
|
|
23
|
-
"engines": {
|
|
24
|
-
"node": ">=24 <25"
|
|
25
|
-
}
|
|
26
|
-
}
|
|
@@ -1,23 +0,0 @@
|
|
|
1
|
-
import type { Logger } from "./logger.js";
|
|
2
|
-
|
|
3
|
-
export type ErrorContext = Readonly<Record<string, unknown>>;
|
|
4
|
-
|
|
5
|
-
/** Where unexpected errors are sent. Implement this for a hosted error-tracking service. */
|
|
6
|
-
export interface ErrorReporter {
|
|
7
|
-
readonly report: (error: unknown, context?: ErrorContext) => void;
|
|
8
|
-
}
|
|
9
|
-
|
|
10
|
-
/** Reports errors through a {@link Logger}. No external service is involved. */
|
|
11
|
-
export function createLoggerErrorReporter(logger: Logger): ErrorReporter {
|
|
12
|
-
return {
|
|
13
|
-
report(error, context = {}) {
|
|
14
|
-
logger.error(
|
|
15
|
-
error instanceof Error ? error.message : "Non-error thrown",
|
|
16
|
-
{
|
|
17
|
-
...context,
|
|
18
|
-
errorName: error instanceof Error ? error.name : typeof error,
|
|
19
|
-
}
|
|
20
|
-
);
|
|
21
|
-
},
|
|
22
|
-
};
|
|
23
|
-
}
|
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
export { createLoggerErrorReporter } from "./error-reporting.js";
|
|
2
|
-
export type { ErrorContext, ErrorReporter } from "./error-reporting.js";
|
|
3
|
-
export { consoleJsonSink, createLogger, logLevels } from "./logger.js";
|
|
4
|
-
export type {
|
|
5
|
-
LogFields,
|
|
6
|
-
Logger,
|
|
7
|
-
LoggerOptions,
|
|
8
|
-
LogLevel,
|
|
9
|
-
LogRecord,
|
|
10
|
-
LogSink,
|
|
11
|
-
} from "./logger.js";
|
|
12
|
-
export { inactiveTracer, withSpan } from "./tracing.js";
|
|
13
|
-
export type { Span, SpanAttributes, Tracer } from "./tracing.js";
|