@mailwoman/sqlite 9.4.0 → 10.1.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/lib/batched.ts +7 -13
- package/lib/client.ts +15 -42
- package/lib/database-schema.ts +2 -20
- package/lib/dialect.ts +1 -1
- package/lib/driver.ts +3 -3
- package/lib/index.ts +7 -6
- package/lib/introspection.ts +15 -8
- package/lib/lookup.ts +77 -0
- package/lib/schema-columns.ts +18 -19
- package/lib/{sealed-build.ts → sealed/build.ts} +15 -26
- package/lib/sealed/db.ts +191 -0
- package/lib/sealed.ts +14 -9
- package/out/batched.d.ts +7 -13
- package/out/batched.d.ts.map +1 -1
- package/out/batched.js +3 -5
- package/out/batched.js.map +1 -1
- package/out/client.d.ts +14 -41
- package/out/client.d.ts.map +1 -1
- package/out/client.js +9 -17
- package/out/client.js.map +1 -1
- package/out/database-schema.d.ts +2 -20
- package/out/database-schema.d.ts.map +1 -1
- package/out/database-schema.js +1 -14
- package/out/database-schema.js.map +1 -1
- package/out/{dialect-config.d.ts → dialect/config.d.ts} +1 -1
- package/out/dialect/config.d.ts.map +1 -0
- package/out/{dialect-config.js → dialect/config.js} +1 -1
- package/out/dialect/config.js.map +1 -0
- package/out/dialect.d.ts +1 -1
- package/out/dialect.d.ts.map +1 -1
- package/out/driver.d.ts +1 -1
- package/out/driver.d.ts.map +1 -1
- package/out/driver.js +2 -2
- package/out/driver.js.map +1 -1
- package/out/index.d.ts +7 -6
- package/out/index.d.ts.map +1 -1
- package/out/index.js +7 -6
- package/out/index.js.map +1 -1
- package/out/introspection.d.ts +15 -8
- package/out/introspection.d.ts.map +1 -1
- package/out/introspection.js +15 -8
- package/out/introspection.js.map +1 -1
- package/out/lookup.d.ts +49 -0
- package/out/lookup.d.ts.map +1 -0
- package/out/lookup.js +55 -0
- package/out/lookup.js.map +1 -0
- package/out/schema-columns.d.ts +18 -19
- package/out/schema-columns.d.ts.map +1 -1
- package/out/schema-columns.js +14 -17
- package/out/schema-columns.js.map +1 -1
- package/out/sealed/build.d.ts +40 -0
- package/out/sealed/build.d.ts.map +1 -0
- package/out/{sealed-build.js → sealed/build.js} +3 -16
- package/out/sealed/build.js.map +1 -0
- package/out/sealed/db.d.ts +90 -0
- package/out/sealed/db.d.ts.map +1 -0
- package/out/{sealed-db.js → sealed/db.js} +63 -43
- package/out/sealed/db.js.map +1 -0
- package/out/sealed.d.ts +12 -8
- package/out/sealed.d.ts.map +1 -1
- package/out/sealed.js +11 -8
- package/out/sealed.js.map +1 -1
- package/out/tsconfig.test.tsbuildinfo +1 -1
- package/package.json +15 -104
- package/lib/sealed-db.ts +0 -170
- package/out/dialect-config.d.ts.map +0 -1
- package/out/dialect-config.js.map +0 -1
- package/out/sealed-build.d.ts +0 -51
- package/out/sealed-build.d.ts.map +0 -1
- package/out/sealed-build.js.map +0 -1
- package/out/sealed-db.d.ts +0 -74
- package/out/sealed-db.d.ts.map +0 -1
- package/out/sealed-db.js.map +0 -1
- /package/lib/{dialect-config.ts → dialect/config.ts} +0 -0
package/lib/sealed-db.ts
DELETED
|
@@ -1,170 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* @copyright Sister Software
|
|
3
|
-
* @license AGPL-3.0
|
|
4
|
-
* @author Teffen Ellis, et al.
|
|
5
|
-
*
|
|
6
|
-
* The sealed-artifact invariant: every SQLite DB a build produces is a READ-ONLY asset. `sealDatabase`
|
|
7
|
-
* is the last step of every builder — checkpoint, freeze the journal, chmod 0444. `openBuiltClient`
|
|
8
|
-
* (`@mailwoman/sqlite/sealed`) is how anything opens a data artifact; a write-mode open of a sealed
|
|
9
|
-
* file throws a NAMED error pointing at the rebuild command instead of a cryptic SQLITE_READONLY. Unsealing is deliberate and
|
|
10
|
-
* manual (`chmod u+w`), never programmatic — rebuild, don't mutate.
|
|
11
|
-
*
|
|
12
|
-
* `swapDatabaseIntoPlace` is the other half of that invariant — the atomic publish step AGENTS.md
|
|
13
|
-
* specifies in prose ("build it successfully, then move the previous version to a temp directory,
|
|
14
|
-
* and then move the new version into place"). It lives here because this module already owns the
|
|
15
|
-
* built-artifact lifecycle, and because a rule the project states in prose and implements more than
|
|
16
|
-
* once in code should be a function.
|
|
17
|
-
*/
|
|
18
|
-
|
|
19
|
-
import type { DatabaseSync } from "node:sqlite"
|
|
20
|
-
|
|
21
|
-
import { pathExists, statPath } from "@mailwoman/core/fs/readers"
|
|
22
|
-
import { changeMode, movePath, removePath, removePathIfPresent } from "@mailwoman/core/fs/writers"
|
|
23
|
-
import { basename } from "path-ts"
|
|
24
|
-
|
|
25
|
-
/**
|
|
26
|
-
* The one capability {@link assertDatabaseIntegrity} needs. Narrowing to it rather than naming a handle type lets a
|
|
27
|
-
* `DatabaseClient` satisfy the parameter with no import and no cast.
|
|
28
|
-
*/
|
|
29
|
-
type IntegrityProbe = Pick<DatabaseSync, "prepare">
|
|
30
|
-
|
|
31
|
-
/**
|
|
32
|
-
* `node:sqlite` via {@link process.getBuiltinModule} — invisible to bundlers. A static import here would ride the
|
|
33
|
-
* `@mailwoman/core/utils` barrel into every consumer, and the docs' plugin loader (which transpiles `docusaurus.config`
|
|
34
|
-
* imports) can't resolve `node:sqlite` (CI: "Cannot find module 'sqlite'"). The builtin accessor keeps `node:sqlite`
|
|
35
|
-
* out of the static import graph with zero resolve surface.
|
|
36
|
-
*/
|
|
37
|
-
function sqlite(): typeof import("node:sqlite") {
|
|
38
|
-
return process.getBuiltinModule("node:sqlite")
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
/**
|
|
42
|
-
* A write-mode open was attempted on a sealed (0444) data artifact.
|
|
43
|
-
*/
|
|
44
|
-
export class SealedArtifactError extends Error {
|
|
45
|
-
constructor(path: string) {
|
|
46
|
-
super(
|
|
47
|
-
`${basename(path)} is a sealed read-only artifact — rebuild it via \`mailwoman gazetteer build …\`, ` +
|
|
48
|
-
`don't mutate it. (Deliberate unseal: chmod u+w — but prefer a rebuild.)`
|
|
49
|
-
)
|
|
50
|
-
|
|
51
|
-
this.name = "SealedArtifactError"
|
|
52
|
-
}
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
/**
|
|
56
|
-
* True when the artifact exists and carries no write bits (the sealed state {@link sealDatabase} leaves).
|
|
57
|
-
*/
|
|
58
|
-
export async function isSealed(path: string): Promise<boolean> {
|
|
59
|
-
return (await pathExists(path)) && ((await statPath(path)).mode & 0o222) === 0
|
|
60
|
-
}
|
|
61
|
-
|
|
62
|
-
/**
|
|
63
|
-
* Finalize a built DB: WAL-checkpoint → `journal_mode = DELETE` → remove `-wal`/`-shm` sidecars → `chmod 0o444`.
|
|
64
|
-
* Idempotent. Throws if the checkpoint cannot complete (another writer holds the DB).
|
|
65
|
-
*/
|
|
66
|
-
export async function sealDatabase(path: string): Promise<void> {
|
|
67
|
-
// A previously sealed artifact needs the write bit back for the journal-mode switch.
|
|
68
|
-
if (await isSealed(path)) {
|
|
69
|
-
await changeMode(path, 0o644)
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
let mode: { journal_mode: string }
|
|
73
|
-
|
|
74
|
-
{
|
|
75
|
-
using db = new (sqlite().DatabaseSync)(path)
|
|
76
|
-
const checkpoint = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get() as { busy: number }
|
|
77
|
-
|
|
78
|
-
if (checkpoint.busy !== 0) {
|
|
79
|
-
throw new Error(`sealDatabase: WAL checkpoint busy on ${path} — close all writers first`)
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
mode = db.prepare("PRAGMA journal_mode = DELETE").get() as { journal_mode: string }
|
|
83
|
-
}
|
|
84
|
-
|
|
85
|
-
if (mode.journal_mode !== "delete") {
|
|
86
|
-
throw new Error(`sealDatabase: journal_mode switch failed on ${path} (still ${mode.journal_mode})`)
|
|
87
|
-
}
|
|
88
|
-
|
|
89
|
-
for (const sidecar of [`${path}-wal`, `${path}-shm`]) {
|
|
90
|
-
if (await pathExists(sidecar)) {
|
|
91
|
-
await removePath(sidecar)
|
|
92
|
-
}
|
|
93
|
-
}
|
|
94
|
-
|
|
95
|
-
await changeMode(path, 0o444)
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
/**
|
|
99
|
-
* Verify a freshly-built database is not corrupt, immediately before it is sealed and published.
|
|
100
|
-
*
|
|
101
|
-
* Belongs beside {@link sealDatabase} for the same reason `swapDatabaseIntoPlace` does: the check is part of the
|
|
102
|
-
* built-artifact lifecycle, and every builder was running it from its own copy. `integrity_check` answers with the
|
|
103
|
-
* single row `{ integrity_check: "ok" }` on a healthy file and one row per problem otherwise, so only the first matters
|
|
104
|
-
* — a builder that reads the column and compares it to `"ok"` has done the whole check.
|
|
105
|
-
*
|
|
106
|
-
* @throws When the database reports anything other than `ok`, naming the artifact and what SQLite said.
|
|
107
|
-
*/
|
|
108
|
-
export function assertDatabaseIntegrity(db: IntegrityProbe, artifact: string): void {
|
|
109
|
-
const row = db.prepare("PRAGMA integrity_check").get() as { integrity_check: string } | undefined
|
|
110
|
-
const verdict = row?.integrity_check
|
|
111
|
-
|
|
112
|
-
if (verdict !== "ok") {
|
|
113
|
-
throw new Error(`integrity_check failed on ${basename(artifact)}: ${verdict ?? "no result"}`)
|
|
114
|
-
}
|
|
115
|
-
}
|
|
116
|
-
|
|
117
|
-
/**
|
|
118
|
-
* Refuse a write-mode open of a sealed artifact, naming the rebuild command instead of letting SQLite answer
|
|
119
|
-
* `SQLITE_READONLY`.
|
|
120
|
-
*
|
|
121
|
-
* The open itself lives in `@mailwoman/sqlite/sealed` — `openBuiltClient`, which every caller uses. This half stays
|
|
122
|
-
* here because it is a filesystem predicate, and because this module reaches `node:sqlite` through
|
|
123
|
-
* {@link process.getBuiltinModule} to keep the `@mailwoman/core/utils` barrel free of it.
|
|
124
|
-
*
|
|
125
|
-
* @throws {SealedArtifactError} When `path` is sealed.
|
|
126
|
-
*/
|
|
127
|
-
export async function assertUnsealedForWrite(path: string): Promise<void> {
|
|
128
|
-
if (await isSealed(path)) throw new SealedArtifactError(path)
|
|
129
|
-
}
|
|
130
|
-
|
|
131
|
-
/**
|
|
132
|
-
* Atomically move a freshly-built database into its published location.
|
|
133
|
-
*
|
|
134
|
-
* The build writes to a temp path, so a mid-build crash never leaves a half-written DB at `finalPath`. This moves any
|
|
135
|
-
* prior version aside, slots the new one in, then drops the old — the previous file stays intact until the replacement
|
|
136
|
-
* is committed, and the `-wal`/`-shm` siblings of BOTH paths are cleared so a stale journal can never be paired with a
|
|
137
|
-
* new main file.
|
|
138
|
-
*
|
|
139
|
-
* Sealing (`sealDatabase`) happens on the temp file BEFORE the swap: a sealed artifact is what gets published, and 0444
|
|
140
|
-
* does not prevent a rename.
|
|
141
|
-
*/
|
|
142
|
-
export async function swapDatabaseIntoPlace(tmpPath: string, finalPath: string): Promise<void> {
|
|
143
|
-
const aside = `${finalPath}.old-${process.pid}`
|
|
144
|
-
|
|
145
|
-
if (await pathExists(finalPath)) {
|
|
146
|
-
await movePath(finalPath, aside)
|
|
147
|
-
}
|
|
148
|
-
|
|
149
|
-
for (const sfx of ["-wal", "-shm"]) {
|
|
150
|
-
await removePathIfPresent(finalPath + sfx)
|
|
151
|
-
}
|
|
152
|
-
|
|
153
|
-
try {
|
|
154
|
-
await movePath(tmpPath, finalPath)
|
|
155
|
-
} catch (error) {
|
|
156
|
-
// The prior version is already aside at this point — a failed forward rename must not leave
|
|
157
|
-
// the slot empty while a restorable artifact sits one rename away.
|
|
158
|
-
if ((await pathExists(aside)) && !(await pathExists(finalPath))) {
|
|
159
|
-
await movePath(aside, finalPath)
|
|
160
|
-
}
|
|
161
|
-
|
|
162
|
-
throw error
|
|
163
|
-
}
|
|
164
|
-
|
|
165
|
-
for (const sfx of ["-wal", "-shm"]) {
|
|
166
|
-
await removePathIfPresent(tmpPath + sfx)
|
|
167
|
-
}
|
|
168
|
-
|
|
169
|
-
await removePathIfPresent(aside)
|
|
170
|
-
}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"dialect-config.d.ts","sourceRoot":"","sources":["../lib/dialect-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAA;AAEhD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;;;OAMG;IACH,QAAQ,EAAE,YAAY,GAAG,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,CAAA;IAEtD;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtE"}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"dialect-config.js","sourceRoot":"","sources":["../lib/dialect-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}
|
package/out/sealed-build.d.ts
DELETED
|
@@ -1,51 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* @copyright Sister Software
|
|
3
|
-
* @license AGPL-3.0
|
|
4
|
-
* @author Teffen Ellis, et al.
|
|
5
|
-
*
|
|
6
|
-
* The sealed polygon-artifact build sequence: one temp file beside the destination, two handles, every
|
|
7
|
-
* cleanup path, then `VACUUM` → seal → atomic swap.
|
|
8
|
-
*
|
|
9
|
-
* THE INGEST AND THE FINISH PHASES USE SEPARATE HANDLES, ALWAYS — including the in-process path, which does
|
|
10
|
-
* not need them separated. The batched path DOES: its children open the same file, so the parent's handle
|
|
11
|
-
* has to be closed across them, and a single shared handle silently becomes a closed one by the time the
|
|
12
|
-
* finish phase runs. Doing it one way in both paths is what puts the fixture suites on the same sequence a
|
|
13
|
-
* national build takes.
|
|
14
|
-
*/
|
|
15
|
-
import { DatabaseClient } from "#client";
|
|
16
|
-
export interface BuildSealedArtifactOptions<DB, Streamed, Result> {
|
|
17
|
-
/**
|
|
18
|
-
* Where the sealed artifact lands. The build writes beside it and swaps.
|
|
19
|
-
*/
|
|
20
|
-
out: string;
|
|
21
|
-
/**
|
|
22
|
-
* Create every table the build writes — the layer's own, the contract's, and any build-only scratch table (which the
|
|
23
|
-
* finish phase drops before the artifact is sealed).
|
|
24
|
-
*/
|
|
25
|
-
createTables: (database: DatabaseClient<DB>) => Promise<void>;
|
|
26
|
-
/**
|
|
27
|
-
* The in-process ingest, run under the FIRST handle. Return `undefined` to defer to {@link batched}; any writes made
|
|
28
|
-
* before deferring (attribute preloads) are kept.
|
|
29
|
-
*/
|
|
30
|
-
ingest: (database: DatabaseClient<DB>) => Promise<Streamed | undefined>;
|
|
31
|
-
/**
|
|
32
|
-
* The bounded child-process ingest, run while the parent holds NO handle. Each child opens the temp file and appends;
|
|
33
|
-
* chunks run one at a time, so there is exactly one writer at every instant.
|
|
34
|
-
*/
|
|
35
|
-
batched?: (tmpPath: string) => Promise<Streamed>;
|
|
36
|
-
/**
|
|
37
|
-
* Post-ingest work under the SECOND handle: assertions over what was streamed, index/coverage/manifest writes,
|
|
38
|
-
* dropping any scratch table. `VACUUM`, the seal and the swap follow; the artifact's on-disk size is measurable only
|
|
39
|
-
* after this returns and the swap lands.
|
|
40
|
-
*/
|
|
41
|
-
finish: (database: DatabaseClient<DB>, streamed: Streamed) => Promise<Result>;
|
|
42
|
-
}
|
|
43
|
-
/**
|
|
44
|
-
* Run one sealed-artifact build.
|
|
45
|
-
*
|
|
46
|
-
* Every failure path removes the temp file: a failed build otherwise leaves a partial multi-gigabyte file whose name
|
|
47
|
-
* carries this process's pid, so nothing would ever pick it up again — the difference between a retry loop that fails
|
|
48
|
-
* and one that fills a disk.
|
|
49
|
-
*/
|
|
50
|
-
export declare function buildSealedArtifact<DB, Streamed, Result>(options: BuildSealedArtifactOptions<DB, Streamed, Result>): Promise<Result>;
|
|
51
|
-
//# sourceMappingURL=sealed-build.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"sealed-build.d.ts","sourceRoot":"","sources":["../lib/sealed-build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAGxC,MAAM,WAAW,0BAA0B,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM;IAC/D;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,YAAY,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7D;;;OAGG;IACH,MAAM,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAA;IACvE;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAChD;;;;OAIG;IACH,MAAM,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC7E;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAC7D,OAAO,EAAE,0BAA0B,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,GACvD,OAAO,CAAC,MAAM,CAAC,CA2DjB"}
|
package/out/sealed-build.js.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"sealed-build.js","sourceRoot":"","sources":["../lib/sealed-build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAEhE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AA8BhE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,OAAyD;IAEzD,MAAM,OAAO,GAAG,GAAG,OAAO,CAAC,GAAG,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAA;IAEnD,IAAI,QAA8B,CAAA;IAElC,CAAC;QACA,YAAY,GAAG,GAAG,IAAI,cAAc,CAAK,OAAO,CAAC,CAAA;QAEjD,IAAI,CAAC;YACJ,GAAG,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;YACrC,GAAG,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;YAEpC,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAA;YAE/B,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;YAC1C,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAA;YAElC,MAAM,KAAK,CAAA;QACZ,CAAC;IACF,CAAC;IAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,wFAAwF,CAAC,CAAA;QAC1G,CAAC;QAED,IAAI,CAAC;YACJ,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;QAC1C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAA;YAElC,MAAM,KAAK,CAAA;QACZ,CAAC;IACF,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,cAAc,CAAK,OAAO,CAAC,CAAA;IAE3C,IAAI,CAAC;QACJ,GAAG,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAA;QACrC,GAAG,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;QAEpC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;QAElD,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAElB,MAAM,GAAG,CAAC,OAAO,EAAE,CAAA;QAEnB,MAAM,YAAY,CAAC,OAAO,CAAC,CAAA;QAC3B,MAAM,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAA;QAEjD,OAAO,MAAM,CAAA;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QAC1C,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAA;QAElC,MAAM,KAAK,CAAA;IACZ,CAAC;AACF,CAAC"}
|
package/out/sealed-db.d.ts
DELETED
|
@@ -1,74 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* @copyright Sister Software
|
|
3
|
-
* @license AGPL-3.0
|
|
4
|
-
* @author Teffen Ellis, et al.
|
|
5
|
-
*
|
|
6
|
-
* The sealed-artifact invariant: every SQLite DB a build produces is a READ-ONLY asset. `sealDatabase`
|
|
7
|
-
* is the last step of every builder — checkpoint, freeze the journal, chmod 0444. `openBuiltClient`
|
|
8
|
-
* (`@mailwoman/sqlite/sealed`) is how anything opens a data artifact; a write-mode open of a sealed
|
|
9
|
-
* file throws a NAMED error pointing at the rebuild command instead of a cryptic SQLITE_READONLY. Unsealing is deliberate and
|
|
10
|
-
* manual (`chmod u+w`), never programmatic — rebuild, don't mutate.
|
|
11
|
-
*
|
|
12
|
-
* `swapDatabaseIntoPlace` is the other half of that invariant — the atomic publish step AGENTS.md
|
|
13
|
-
* specifies in prose ("build it successfully, then move the previous version to a temp directory,
|
|
14
|
-
* and then move the new version into place"). It lives here because this module already owns the
|
|
15
|
-
* built-artifact lifecycle, and because a rule the project states in prose and implements more than
|
|
16
|
-
* once in code should be a function.
|
|
17
|
-
*/
|
|
18
|
-
import type { DatabaseSync } from "node:sqlite";
|
|
19
|
-
/**
|
|
20
|
-
* The one capability {@link assertDatabaseIntegrity} needs. Narrowing to it rather than naming a handle type lets a
|
|
21
|
-
* `DatabaseClient` satisfy the parameter with no import and no cast.
|
|
22
|
-
*/
|
|
23
|
-
type IntegrityProbe = Pick<DatabaseSync, "prepare">;
|
|
24
|
-
/**
|
|
25
|
-
* A write-mode open was attempted on a sealed (0444) data artifact.
|
|
26
|
-
*/
|
|
27
|
-
export declare class SealedArtifactError extends Error {
|
|
28
|
-
constructor(path: string);
|
|
29
|
-
}
|
|
30
|
-
/**
|
|
31
|
-
* True when the artifact exists and carries no write bits (the sealed state {@link sealDatabase} leaves).
|
|
32
|
-
*/
|
|
33
|
-
export declare function isSealed(path: string): Promise<boolean>;
|
|
34
|
-
/**
|
|
35
|
-
* Finalize a built DB: WAL-checkpoint → `journal_mode = DELETE` → remove `-wal`/`-shm` sidecars → `chmod 0o444`.
|
|
36
|
-
* Idempotent. Throws if the checkpoint cannot complete (another writer holds the DB).
|
|
37
|
-
*/
|
|
38
|
-
export declare function sealDatabase(path: string): Promise<void>;
|
|
39
|
-
/**
|
|
40
|
-
* Verify a freshly-built database is not corrupt, immediately before it is sealed and published.
|
|
41
|
-
*
|
|
42
|
-
* Belongs beside {@link sealDatabase} for the same reason `swapDatabaseIntoPlace` does: the check is part of the
|
|
43
|
-
* built-artifact lifecycle, and every builder was running it from its own copy. `integrity_check` answers with the
|
|
44
|
-
* single row `{ integrity_check: "ok" }` on a healthy file and one row per problem otherwise, so only the first matters
|
|
45
|
-
* — a builder that reads the column and compares it to `"ok"` has done the whole check.
|
|
46
|
-
*
|
|
47
|
-
* @throws When the database reports anything other than `ok`, naming the artifact and what SQLite said.
|
|
48
|
-
*/
|
|
49
|
-
export declare function assertDatabaseIntegrity(db: IntegrityProbe, artifact: string): void;
|
|
50
|
-
/**
|
|
51
|
-
* Refuse a write-mode open of a sealed artifact, naming the rebuild command instead of letting SQLite answer
|
|
52
|
-
* `SQLITE_READONLY`.
|
|
53
|
-
*
|
|
54
|
-
* The open itself lives in `@mailwoman/sqlite/sealed` — `openBuiltClient`, which every caller uses. This half stays
|
|
55
|
-
* here because it is a filesystem predicate, and because this module reaches `node:sqlite` through
|
|
56
|
-
* {@link process.getBuiltinModule} to keep the `@mailwoman/core/utils` barrel free of it.
|
|
57
|
-
*
|
|
58
|
-
* @throws {SealedArtifactError} When `path` is sealed.
|
|
59
|
-
*/
|
|
60
|
-
export declare function assertUnsealedForWrite(path: string): Promise<void>;
|
|
61
|
-
/**
|
|
62
|
-
* Atomically move a freshly-built database into its published location.
|
|
63
|
-
*
|
|
64
|
-
* The build writes to a temp path, so a mid-build crash never leaves a half-written DB at `finalPath`. This moves any
|
|
65
|
-
* prior version aside, slots the new one in, then drops the old — the previous file stays intact until the replacement
|
|
66
|
-
* is committed, and the `-wal`/`-shm` siblings of BOTH paths are cleared so a stale journal can never be paired with a
|
|
67
|
-
* new main file.
|
|
68
|
-
*
|
|
69
|
-
* Sealing (`sealDatabase`) happens on the temp file BEFORE the swap: a sealed artifact is what gets published, and 0444
|
|
70
|
-
* does not prevent a rename.
|
|
71
|
-
*/
|
|
72
|
-
export declare function swapDatabaseIntoPlace(tmpPath: string, finalPath: string): Promise<void>;
|
|
73
|
-
export {};
|
|
74
|
-
//# sourceMappingURL=sealed-db.d.ts.map
|
package/out/sealed-db.d.ts.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"sealed-db.d.ts","sourceRoot":"","sources":["../lib/sealed-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAM/C;;;GAGG;AACH,KAAK,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAA;AAYnD;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBACjC,IAAI,EAAE,MAAM;CAQxB;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE7D;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8B9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAOlF;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAExE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B7F"}
|
package/out/sealed-db.js.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"sealed-db.js","sourceRoot":"","sources":["../lib/sealed-db.ts"],"names":[],"mappings":"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"}
|
|
File without changes
|