96 lines
4.4 KiB
JavaScript
96 lines
4.4 KiB
JavaScript
// The record of a memory change that is about to be published.
|
|
//
|
|
// A change touches more than one file (the entry, the Index that links a topic, the
|
|
// change log), and each of them is written on its own, so an interruption can leave
|
|
// half of it done: an entry without its row in the change log, a topic without its
|
|
// link. This keeps the record of what the change will do, so the change can be
|
|
// finished later instead of being half done.
|
|
//
|
|
// The record is written before the change is published, and it is what accepts the
|
|
// change: before the record is there, nothing has changed. It holds the files to
|
|
// write, the files to remove, and the row that goes with them in the change log, so
|
|
// finishing a change later is the same work as publishing it in the first place.
|
|
import { readFileSync } from 'node:fs'
|
|
import { join, relative, resolve, sep } from 'node:path'
|
|
|
|
// The record inside the memory folder.
|
|
export const PENDING_FILE = 'pending.json'
|
|
// A record that cannot be read or understood stops the memory: what it would have
|
|
// changed is unknown, so nothing goes on until it is fixed.
|
|
const PENDING = 'memory/pending'
|
|
// A change is one entry, so its record stays small; a larger one was not written by
|
|
// this.
|
|
const MAX_BYTES = 1_048_576
|
|
|
|
export function pendingPath(root) {
|
|
return join(root, PENDING_FILE)
|
|
}
|
|
|
|
// A path inside the memory folder, as the record holds it: relative, so the folder
|
|
// can be moved, and never outside it.
|
|
export function inside(root, path) {
|
|
const base = resolve(root)
|
|
const full = resolve(base, path)
|
|
if (full !== base && !full.startsWith(base + sep)) throw new Error(`the path ${path} is outside the memory folder`)
|
|
return full
|
|
}
|
|
|
|
// The path of a file in the memory folder, as the record holds it.
|
|
export function relativePath(root, path) {
|
|
return relative(resolve(root), resolve(path)).split(sep).join('/')
|
|
}
|
|
|
|
// The record of a change: what it does, and the row that goes with it.
|
|
export function record({ id, time, op, scope, steps, row }) {
|
|
return { id, time, op, scope, steps, row: { time, id, ...row } }
|
|
}
|
|
|
|
// The record of a change, as it is written down. A record that would be too large is
|
|
// refused: the memory folder holds one change at a time, and a record that cannot be
|
|
// read back would stop the memory for good. The size is the same one the read side
|
|
// uses, so a record that is written can always be read.
|
|
export function serialize(record) {
|
|
const text = JSON.stringify(record)
|
|
const size = Buffer.byteLength(text)
|
|
if (size > MAX_BYTES) {
|
|
throw Object.assign(new Error(`The memory change is too large to record (${size} of ${MAX_BYTES} bytes). Make the memory file smaller first.`), { code: 'memory/too-large' })
|
|
}
|
|
return text
|
|
}
|
|
|
|
// The record waiting to be finished, if there is one. A record that cannot be read
|
|
// or understood is an error, not an empty record: the change it holds is unknown,
|
|
// and a change that is half done must not be passed over.
|
|
export function read(root) {
|
|
const path = pendingPath(root)
|
|
let text
|
|
try {
|
|
text = readFileSync(path, 'utf8')
|
|
} catch (error) {
|
|
if (error?.code === 'ENOENT') return undefined
|
|
throw Object.assign(new Error(`${PENDING_FILE} could not be read (${error?.code ?? error?.message})`), { code: PENDING })
|
|
}
|
|
if (Buffer.byteLength(text) > MAX_BYTES) {
|
|
throw Object.assign(new Error(`${PENDING_FILE} is larger than a memory change record`), { code: PENDING })
|
|
}
|
|
let value
|
|
try {
|
|
value = JSON.parse(text)
|
|
} catch (error) {
|
|
throw Object.assign(new Error(`${PENDING_FILE} is not readable (${error.message})`), { code: PENDING })
|
|
}
|
|
if (!wellFormed(value)) throw Object.assign(new Error(`${PENDING_FILE} is not a memory change record`), { code: PENDING })
|
|
return value
|
|
}
|
|
|
|
const wellFormed = (value) => {
|
|
if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
|
|
if (typeof value.id !== 'string' || value.id === '') return false
|
|
if (typeof value.op !== 'string' || typeof value.scope !== 'string') return false
|
|
if (!Array.isArray(value.steps) || value.steps.length === 0) return false
|
|
if (!value.steps.every(step => step !== null && typeof step === 'object' && typeof step.path === 'string' && step.path !== ''
|
|
&& (step.action === 'remove' ? step.text === undefined : step.action === 'write' && typeof step.text === 'string'))) return false
|
|
if (value.row === null || typeof value.row !== 'object' || Array.isArray(value.row)) return false
|
|
return typeof value.row.id === 'string' && value.row.id !== ''
|
|
}
|