@khorsheed/dsh-reader 0.2.0

package/lib/types/store.d.ts

@@ -0,0 +1,224 @@
+import { type ReaderEntryAnnotation, type ReaderStateDoc, type ReaderTranslationMemoryEntry } from './types.ts';
+/** How many tags one document may define (a vocabulary, not a folksonomy dump). */
+export declare const MAX_TAGS = 200;
+/** How many entries may carry fetched bodies, before the newest-first eviction. */
+export declare const MAX_CACHED_BODIES = 500;
+/** The state file name inside the plugin's state root. */
+export declare const READER_STATE_FILE_NAME = "state.json";
+/** A store failure that the service maps onto a wire outcome. */
+export declare class ReaderStoreError extends Error {
+    readonly kind: 'io' | 'corrupt';
+    constructor(message: string, kind: 'io' | 'corrupt');
+}
+/** A read result: the document plus the token the next write must present. */
+export interface ReaderStoreRead {
+    readonly doc: ReaderStateDoc;
+    /**
+     * The document's freshness token, or `null` when there is no file yet.
+     *
+     * Only this process writes the reader's state, so the token exists to make a
+     * same-process read-modify-write honest (an external editor between the two
+     * is detected) rather than to coordinate writers.
+     */
+    readonly version: string | null;
+}
+/**
+ * Resolve the state root: an explicit config value wins, then
+ * `$DSH_HOME/state/dsh-reader`, then `<cwd>/.dsh-reader`.
+ *
+ * @param configured - the plugin-provided override, if any.
+ * @returns the absolute state root directory.
+ */
+export declare function resolveReaderStateRoot(configured: string | undefined): string;
+/** The empty document. */
+export declare function emptyStateDoc(): ReaderStateDoc;
+/** Serialize the document (trailing newline, the repo's state-file shape). */
+export declare function serializeStateDoc(doc: ReaderStateDoc): string;
+/**
+ * Coerce a parsed value into a document, dropping anything unrecognizable
+ * rather than trusting the file: this is user-editable state.
+ *
+ * @param value - the parsed JSON.
+ * @returns a valid document.
+ */
+export declare function normalizeStateDoc(value: unknown): ReaderStateDoc;
+/**
+ * How many opened entries the recent list keeps.
+ *
+ * A bounded list is what makes the page useful: the question it answers is
+ * "what was I just reading", and a year of history answers it worse than the
+ * last hundred items. The cap is also what keeps `state.json` small, since this
+ * is the one table that grows with READING rather than with sources.
+ */
+export declare const MAX_RECENT_ENTRIES = 100;
+/**
+ * Bound the document's payload bytes without dropping a subscription.
+ *
+ * Newest-first: the freshest payload is the one the reader is most likely to
+ * open, so it survives and the oldest bodies are the ones released. Keeping
+ * every source row regardless is deliberate — a source whose body was evicted
+ * still refreshes, and dropping subscriptions to save space would be a silent
+ * data loss the reader never asked for.
+ *
+ * @param doc - the document to bound.
+ * @returns the bounded document, and whether anything was released.
+ */
+export declare function boundPayloads(doc: ReaderStateDoc): {
+    doc: ReaderStateDoc;
+    changed: boolean;
+};
+/** Sub-directory holding bodies too large to inline in the document. */
+export declare const READER_BODIES_DIR = "bodies";
+/**
+ * The global translation memory's file name inside `bodies/`.
+ *
+ * One fixed name rather than a per-key hash: the table is a single artifact,
+ * rewritten whole by the (already debounced) write path, and referenced from
+ * the document's `translationMemory` manifest so `pruneBodies` keeps it.
+ */
+export declare const TRANSLATION_MEMORY_FILE = "translation-memory.json";
+/** Native-fs state store: the deployment's document, not the session's. */
+export declare class ReaderStore {
+    private readonly stateRoot;
+    private readonly file;
+    private readonly bodiesDir;
+    /** Set once the root has proven unwritable; the service then goes memory-only. */
+    private unwritable;
+    /**
+     * @param config - optional state-root override.
+     */
+    constructor(config?: {
+        stateRoot?: string;
+    });
+    /**
+     * Write one body to its own file, atomically, and return the file's name.
+     *
+     * The name is a digest of the entry id: entry ids are URLs, and a document
+     * carrying an absolute path (or a path derived from remote text) is a
+     * directory-traversal waiting to happen.
+     *
+     * @param entryId - the entry the body belongs to.
+     * @param html - the normalized body markup.
+     * @returns the file name to store in the document.
+     */
+    writeBody(entryId: string, html: string): string;
+    /**
+     * Write one NAMED artifact into `bodies/`, atomically.
+     *
+     * Unlike {@link writeBody} the name is the caller's, not a hash of an entry
+     * id: the global translation memory is one fixed file, not one per entry. The
+     * name is validated to a bare file name — this directory must never grow a
+     * path.
+     *
+     * @param name - the bare file name to write.
+     * @param content - the file's content.
+     * @returns the name written.
+     */
+    writeNamedBody(name: string, content: string): string;
+    /**
+     * Read one body file.
+     *
+     * @param name - the file name recorded in the document.
+     * @returns the markup, or `undefined` when the file is gone or unreadable.
+     */
+    readBody(name: string): string | undefined;
+    /**
+     * Delete body files the document no longer references.
+     *
+     * Eviction (`maxEntries`), tag edits that drop an annotation, and a hand-edited
+     * document all release bodies by REMOVING them from the JSON — which would
+     * otherwise leave their files on disk forever. Best-effort by design: a failed
+     * sweep must never fail the commit that triggered it.
+     *
+     * @param doc - the document that was just written.
+     * @returns how many files were removed.
+     */
+    pruneBodies(doc: ReaderStateDoc): number;
+    /** The absolute path of the state file (diagnostics and tests). */
+    get path(): string;
+    /** Why persistence is unavailable, when it is. */
+    get unavailableReason(): string | undefined;
+    /**
+     * Whether persistence is available.
+     *
+     * Probed by creating the state root, not by asking a capability: a
+     * read-only deployment (a container with no writable home) must degrade to
+     * memory-only, and that is only knowable by trying.
+     */
+    get available(): boolean;
+    /**
+     * Read the document tolerantly.
+     *
+     * @returns the document and its freshness token; a missing file reads as empty.
+     * @throws ReaderStoreError when the file exists but does not parse.
+     */
+    read(): Promise<ReaderStoreRead>;
+    /**
+     * Write the document atomically under the token from the last read.
+     *
+     * @param doc - the document to publish.
+     * @param version - the token from the last read (`null` for the first write).
+     * @returns the new freshness token.
+     */
+    write(doc: ReaderStateDoc, version: string | null): Promise<string>;
+    /**
+     * Read-modify-write with the one concurrent-edit retry.
+     *
+     * @param mutate - pure function from the current document to the next one.
+     * @returns the document that ended up on disk.
+     */
+    update(mutate: (doc: ReaderStateDoc) => ReaderStateDoc): Promise<ReaderStateDoc>;
+}
+/**
+ * Bound the cached article bodies without touching what the reader authored.
+ *
+ * Newest-first: the article just fetched is the one being read, so the budget
+ * releases the older copies. Tags are NOT part of this budget — a tag is a
+ * sentence the reader wrote, and losing it to make room for a cached page would
+ * be the worst trade in this document.
+ *
+ * @param doc - the document to bound.
+ * @returns the bounded document, and whether anything was released.
+ */
+export declare function boundAnnotations(doc: ReaderStateDoc): {
+    doc: ReaderStateDoc;
+    changed: boolean;
+};
+/**
+ * Drop tags nothing references any more.
+ *
+ * @param doc - the document to prune.
+ * @returns the pruned document, and how many tags went.
+ */
+export declare function pruneOrphanTags(doc: ReaderStateDoc): {
+    doc: ReaderStateDoc;
+    removed: number;
+};
+/**
+ * Bound the two translation tiers to their shared budget, LRU by last use.
+ *
+ * The eviction list is ONE ordering across the global memory and every entry's
+ * segment map: a sentence remembered and a per-entry map are the same kind of
+ * thing (a translation that was paid for), so the oldest lastUsedAt goes first
+ * regardless of which tier holds it. Two extra rules ride the same walk,
+ * because it is the only place both tiers are walked: schema-version mismatches
+ * are evicted on sight (the lazy half of "version bump = miss"), and the memory
+ * table answers to its own count cap even when the budget has room.
+ *
+ * Pure over plain records: the service wires the files, this decides.
+ *
+ * @param memory - the global sentence memory (table content).
+ * @param annotations - the document's annotations (entry translations included).
+ * @param budgetChars - the shared budget.
+ * @returns the bounded records, plus WHICH keys each tier lost (the caller
+ *   applies the entry evictions to the freshest document inside its commit).
+ */
+export declare function boundTranslations(memory: Record<string, ReaderTranslationMemoryEntry>, annotations: Record<string, ReaderEntryAnnotation>, budgetChars: number): {
+    memory: Record<string, ReaderTranslationMemoryEntry>;
+    annotations: Record<string, ReaderEntryAnnotation>;
+    evictedMemoryKeys: string[];
+    evictedEntryIds: string[];
+};
+/** The table's approximate size in characters, for the document's manifest. */
+export declare function memoryTableChars(entries: Record<string, ReaderTranslationMemoryEntry>): number;
+//# sourceMappingURL=store.d.ts.map