@docmentis/udoc-node 0.0.1 → 0.8.0

package/dist/node.js

@@ -0,0 +1,96 @@
+// The embedder's entry point: who is running the engine, the fonts it offers,
+// and the engine itself.
+import { CSS2_ENDPOINT } from "@docmentis/udoc-wasm/font-fulfill";
+import { compileEngine } from "./engine.js";
+import { FontCache } from "./font-cache.js";
+import { UDocSession, fetchWhole } from "./session.js";
+import { WRAPPER_VERSION } from "./version.js";
+/** The docMentis component this package is. */
+const WRAPPER = "udoc-node";
+/** The bytes of font files kept when {@link UDocNodeOptions.fontCacheSize} is absent. */
+const FONT_CACHE_SIZE = 64 * 1024 * 1024;
+/**
+ * The udoc engine in this process: the host's identity, and the compiled
+ * engine every session instantiates. Build one per host identity and open as
+ * many documents through it as needed — each is a session of its own, on a
+ * thread of its own.
+ */
+export class UDocNode {
+    #module;
+    #config;
+    #fonts;
+    /** `[]` with Google Fonts off; `undefined` keeps the catalog `startSession` offers. */
+    #googleFontFamilies;
+    #googleFontEndpoint;
+    /** The font files every session opened here shares. */
+    #fontCache;
+    constructor(module, options) {
+        this.#module = module;
+        this.#config = {
+            domain: options.domain ?? "unknown",
+            wrapper: options.wrapper?.name ?? WRAPPER,
+            wrapperVersion: options.wrapper?.version ?? WRAPPER_VERSION,
+            ...(options.license !== undefined ? { license: options.license } : {}),
+            ...(options.distinctId !== undefined ? { distinctId: options.distinctId } : {}),
+            disableTelemetry: options.disableTelemetry ?? false,
+        };
+        this.#fonts = [...(options.fonts ?? [])];
+        this.#googleFontFamilies = options.enableGoogleFonts === false ? [] : options.googleFontFamilies;
+        this.#googleFontEndpoint =
+            options.googleFontEndpoint === undefined ? CSS2_ENDPOINT : new URL(options.googleFontEndpoint).href;
+        this.#fontCache = new FontCache(options.fontCacheSize ?? FONT_CACHE_SIZE, fetchWhole);
+    }
+    /** Compile the bundled engine (once per process) and return a `UDocNode` for it. */
+    static async create(options = {}) {
+        return new UDocNode(await compileEngine(), options);
+    }
+    /**
+     * Open a document from its bytes in a session of its own — as `format` when
+     * given, which skips detection; otherwise the format is detected, and a
+     * `.udoc` zip opens as a package. `delimiter` is the character a CSV's
+     * fields are split by; without it, a comma, or a semicolon where the first
+     * record is split by more of them. No other format takes one.
+     *
+     * Starts the session first, so this is where a license is checked and,
+     * without one, where a permit is spent — on this document, whether or not
+     * it then parses. Rejects with a `UDocError`: a licensing code when the
+     * engine refuses, or the engine's own when the bytes don't open.
+     *
+     * A PDF that needs a password opens waiting for one: the session's
+     * `needsPassword` says so, and its `authenticate` takes the password.
+     */
+    open(bytes, format, delimiter) {
+        return UDocSession.open(this.#init(), this.#fontCache, bytes, format, delimiter);
+    }
+    /**
+     * Open the package a server keeps at `url` in a session of its own, without
+     * downloading it — `url` is its package resource, udoc-server's
+     * `…/documents/{id}/package`, and absolute. Each part is fetched the first
+     * time the document needs it: the open fetches the few it starts from, and a
+     * call that composes a page fetches that page's, rejecting if one can't be
+     * fetched.
+     *
+     * A remote open is an open: this is where a license is checked and, without
+     * one, where a permit is spent. Rejects with a `UDocError`: a licensing code
+     * when the engine refuses, or the engine's own when the package can't be
+     * fetched or read.
+     *
+     * Each URL is fetched with the global `fetch`, unless `fetch` answers it —
+     * the whole body, as the route serves it — which is how udoc-server opens
+     * a session over the store it keeps, with no request to itself.
+     */
+    openRemote(url, fetch) {
+        return UDocSession.openRemote(this.#init(), this.#fontCache, url, fetch);
+    }
+    /** What a session's worker starts with. */
+    #init() {
+        return {
+            module: this.#module,
+            config: this.#config,
+            fonts: this.#fonts,
+            ...(this.#googleFontFamilies !== undefined ? { googleFontFamilies: this.#googleFontFamilies } : {}),
+            googleFontEndpoint: this.#googleFontEndpoint,
+        };
+    }
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"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"}

package/dist/protocol.d.ts

@@ -0,0 +1,151 @@
+import type { MessagePort } from "node:worker_threads";
+import type { Entitlements, ExportFormat, FileFormat, PageExportFormat, SaveStrategy, UDocError, UDocType } from "@docmentis/udoc-wasm";
+/**
+ * What a remote document's parts come to its worker over. The engine asks for a
+ * part the moment it needs one, and waits for it, and Node has no synchronous
+ * HTTP: so the worker posts the part's URL on `port` and blocks until the
+ * session's side has fetched it, posted a {@link FetchAnswer} back, and counted
+ * it in `answered[0]`.
+ */
+export interface FetchChannel {
+    port: MessagePort;
+    answered: Int32Array;
+}
+/** The session side's answer to one URL posted on a {@link FetchChannel}. */
+export type FetchAnswer = {
+    ok: true;
+    body: ArrayBuffer;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * A font file a worker asks its session's side for, on the port its open
+ * carried, from the cache every session of its `UDocNode` shares. `id` pairs it
+ * with its {@link FontFileAnswer}: the worker asks for several at once.
+ */
+export interface FontFileRequest {
+    id: number;
+    url: string;
+}
+/** The session side's answer to a {@link FontFileRequest}: the file, or why it didn't come. */
+export type FontFileAnswer = {
+    id: number;
+    ok: true;
+    body: ArrayBuffer;
+} | {
+    id: number;
+    ok: false;
+    message: string;
+};
+/** A request to the worker. `id` pairs it with its {@link WorkerReply}. */
+export type WorkerRequest = {
+    id: number;
+    type: "open";
+    bytes: Uint8Array;
+    format?: FileFormat;
+    delimiter?: string;
+    fontFiles: MessagePort;
+} | {
+    id: number;
+    type: "openRemote";
+    url: string;
+    fetches: FetchChannel;
+    fontFiles: MessagePort;
+} | {
+    id: number;
+    type: "authenticate";
+    password: string;
+} | {
+    id: number;
+    type: "pageCount";
+} | {
+    id: number;
+    type: "saveToBytes";
+    format: FileFormat;
+    strategy?: SaveStrategy;
+    delimiter?: string;
+} | {
+    id: number;
+    type: "saveToPackage";
+    version?: number;
+} | {
+    id: number;
+    type: "exportToBytes";
+    format: ExportFormat;
+} | {
+    id: number;
+    type: "exportPageToBytes";
+    index: number;
+    format: PageExportFormat;
+} | {
+    id: number;
+    type: "snapshot";
+} | {
+    id: number;
+    type: "versionVector";
+} | {
+    id: number;
+    type: "patchSince";
+    peer: Uint8Array;
+} | {
+    id: number;
+    type: "merge";
+    patch: Uint8Array;
+} | {
+    id: number;
+    type: "presence";
+} | {
+    id: number;
+    type: "mergePresence";
+    presence: Uint8Array;
+};
+/**
+ * What the document opened as: its doc type, the format it came from, whether
+ * it came as a package, and whether it needs a password before it can be read.
+ */
+export interface Opened {
+    docType: UDocType;
+    /** Absent for a package that recorded none. */
+    sourceFormat?: FileFormat;
+    fromPackage: boolean;
+    needsPassword: boolean;
+    /** What the license, or with none the permit, entitled the session to. */
+    entitlements: Entitlements;
+}
+/** What each request's reply carries when it succeeds. */
+export interface WorkerResult {
+    open: Opened;
+    openRemote: Opened;
+    authenticate: boolean;
+    pageCount: number;
+    saveToBytes: Uint8Array;
+    saveToPackage: Uint8Array;
+    exportToBytes: Uint8Array;
+    exportPageToBytes: Uint8Array;
+    snapshot: Uint8Array;
+    versionVector: Uint8Array;
+    patchSince: Uint8Array;
+    merge: undefined;
+    presence: Uint8Array;
+    mergePresence: undefined;
+}
+/**
+ * A failure, as it crosses the thread boundary: an `Error` loses its class on
+ * the way, so the {@link UDocError} the session side rebuilds travels as its
+ * fields. A `crashed` one finishes the session — a wasm instance is not usable
+ * after a trap, since a panic aborts mid-call and can leave a session borrowed
+ * for good; after any other, the session is still good.
+ */
+export type WorkerFailure = Pick<UDocError, "code" | "message" | "detail">;
+/** The worker's answer to a {@link WorkerRequest}. */
+export type WorkerReply = {
+    id: number;
+    ok: true;
+    result: WorkerResult[keyof WorkerResult];
+} | {
+    id: number;
+    ok: false;
+    failure: WorkerFailure;
+};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js

@@ -0,0 +1,3 @@
+// Messages between a session and the worker thread that runs it.
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,iEAAiE"}

package/dist/session.d.ts

@@ -0,0 +1,168 @@
+import { Worker } from "node:worker_threads";
+import type { Entitlements, ExportFormat, FileFormat, PageExportFormat, SaveStrategy, UDocType } from "@docmentis/udoc-wasm";
+import { UDocError } from "@docmentis/udoc-wasm/error";
+/** A server's answer to {@link UDocSession.requestRemoteCheckpoint}: the version of the baseline it wrote. */
+export interface RemoteCheckpointResponse {
+    version: number;
+}
+/**
+ * A session: one open document, driven on a worker thread of its own, so every
+ * call is asynchronous and none blocks the caller's event loop while the engine
+ * composes or rasterizes. As in the engine, the session is its document —
+ * opening one is the open, closing it is the close.
+ *
+ * The thread is held until {@link close}. An idle session does not keep the
+ * process alive; a call in flight does.
+ */
+export declare class UDocSession {
+    #private;
+    /**
+     * Settles once the session can take no more calls, with why: it was
+     * {@link close}d, or its engine crashed or its thread exited on its own —
+     * `crashed`. A host holding sessions watches this to let go of one that
+     * died.
+     */
+    readonly closed: Promise<UDocError>;
+    /** Drive `worker`, which runs `worker.ts`. See {@link UDocSession.open}. */
+    constructor(worker: Worker);
+    /** The open document's doc type (`"portable"`, `"presentation"`, …). */
+    get docType(): UDocType | undefined;
+    /**
+     * The file format the document came from (`"pdf"`, `"pptx"`, …) — what
+     * saving it back means — or `undefined` for a package that recorded none.
+     */
+    get sourceFormat(): FileFormat | undefined;
+    /**
+     * Whether the document was opened from a udoc package rather than
+     * imported from a file — which {@link sourceFormat} alone can't tell,
+     * since a package reports the format it recorded.
+     */
+    get fromPackage(): boolean;
+    /**
+     * Whether the document needs a password before it can be read — a PDF
+     * encrypted with a user password. Until {@link authenticate} unlocks it,
+     * every other call rejects; {@link docType} and {@link sourceFormat} are
+     * already known.
+     */
+    get needsPassword(): boolean;
+    /**
+     * What the license, or with none the permit, entitled the session to — the
+     * `features` a host checks before a call that needs one (the sync calls
+     * need `collaboration`). Advisory: the engine enforces each at the call it
+     * guards, rejecting with a `notEntitled` {@link UDocError}.
+     */
+    get entitlements(): Entitlements | undefined;
+    /**
+     * Unlock the document, which {@link needsPassword needs a password}, with
+     * `password` — its user or its owner password. Resolves `true` once it is
+     * open, and `false` when `password` is refused, the document waiting for
+     * another: try as often as it takes. Not a second open — no further permit
+     * is spent.
+     */
+    authenticate(password: string): Promise<boolean>;
+    /**
+     * How many pages the document's primary plane has.
+     *
+     * A page is known only once it is composed, so this composes the whole
+     * plane — for a long flowing document, the cost of laying out all of it.
+     * Once paid it is not paid again: asking twice, or rendering any page
+     * after, reuses the composed pages. Rejects when a page fails to compose,
+     * since the count is then unknown.
+     */
+    pageCount(): Promise<number>;
+    /**
+     * Save the document as `format`, faithfully — the bytes reopen as the same
+     * document. `format` is one of its doc type's own (a PDF saves to `"pdf"`, a
+     * presentation to `"pptx"`); {@link sourceFormat} is what saving it back
+     * means. `strategy` is how much of the file it was opened from, the
+     * original, the saved bytes keep: a `"delta"` or `"incremental"` save
+     * writes over it, which a session opened with `UDocNode.openRemote` doesn't
+     * hold; without it, the one keeping the most of it that `format` saves by
+     * (`"incremental"` for a PDF, `"rewrite"` for a CSV, a TSV, a PSV or an
+     * image, else `"delta"`). `delimiter` is the character a CSV's fields are
+     * split by; without it, the one the document was opened with, else a comma.
+     * Rejects for a format its doc type doesn't save to, a format that never
+     * saves by `strategy`, a delimiter for a format that takes none, no
+     * original to write over, or a save that isn't built yet.
+     */
+    saveToBytes(format: FileFormat, strategy?: SaveStrategy, delimiter?: string): Promise<Uint8Array>;
+    /**
+     * Save the document as a udoc package — the bytes of a `.udoc` zip, which
+     * `UDocNode.open` reopens. It records the source format, so a reopened package
+     * can still be saved back to it. `version` makes it a checkpoint, baseline
+     * `v<version>`, which keeps the edit log a reopen replays; without it the
+     * package is a flat baseline — the whole document and no log.
+     */
+    saveToPackage(version?: number): Promise<Uint8Array>;
+    /**
+     * Ask the udoc server the document was opened from (`UDocNode.openRemote`)
+     * for a copy of it, saved as its {@link sourceFormat} by `strategy`, else
+     * by the engine's for it — a `"delta"` or `"incremental"` copy is the
+     * server's to save, since only it holds the original. Resolves with the
+     * copy's bytes. Asked with the global
+     * `fetch`, not the one the open was given, which only reads. Rejects for a
+     * document not opened with `UDocNode.openRemote`, or one that records no source
+     * format, and with the server's message for what it refuses.
+     */
+    requestRemoteCopy(strategy?: SaveStrategy): Promise<Uint8Array>;
+    /**
+     * Ask the udoc server the document was opened from (`UDocNode.openRemote`) to
+     * checkpoint it: save its document as a new baseline. Resolves with that
+     * baseline's version. Nothing reopens: this session goes on as it was.
+     * Asked with the global `fetch`, as {@link requestRemoteCopy} is. Rejects
+     * for a document not opened with `UDocNode.openRemote`, and with the server's
+     * message for what it refuses.
+     */
+    requestRemoteCheckpoint(): Promise<RemoteCheckpointResponse>;
+    /**
+     * Export the whole document as `format` — a rendering of its laid-out
+     * pages, fixed and one-way. Rejects until PDF export is built.
+     */
+    exportToBytes(format: ExportFormat): Promise<Uint8Array>;
+    /**
+     * Export page `index` (0-based) of the document's primary plane as
+     * `format` — `{ png: { scale } }`, where `scale` is output pixels per
+     * document point (`1` is 72 DPI).
+     *
+     * Composes the document through that page first — not past it. Rejects
+     * `notFound` when the document turns out to have fewer pages; its message
+     * is the page count.
+     */
+    exportPageToBytes(index: number, format: PageExportFormat): Promise<Uint8Array>;
+    /**
+     * The document's whole editing state — every edit since its baseline — for
+     * a peer that has none of it, to {@link merge}. For a peer that has some,
+     * {@link patchSince} sends only the rest.
+     */
+    snapshot(): Promise<Uint8Array>;
+    /**
+     * Which edits this session holds, as the token a peer's {@link patchSince}
+     * takes to answer with only the ones this session lacks.
+     */
+    versionVector(): Promise<Uint8Array>;
+    /**
+     * The edits this session holds that a peer — named by its
+     * {@link versionVector} — lacks, for that peer's {@link merge}.
+     */
+    patchSince(peer: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Apply a peer's edits — its {@link snapshot} or {@link patchSince} — to the
+     * document. Edits this session already holds are skipped, so merging the
+     * same patch twice changes nothing the second time. Rejects when the bytes
+     * aren't a patch.
+     */
+    merge(patch: Uint8Array): Promise<void>;
+    /**
+     * Every peer's presence this session knows of — each one's selection and
+     * name — for a peer's {@link mergePresence}. Transient: no history, never
+     * part of a save.
+     */
+    presence(): Promise<Uint8Array>;
+    /** Take in a peer's {@link UDocSession.presence}, each peer's latest winning. */
+    mergePresence(presence: Uint8Array): Promise<void>;
+    /** Release the document and its thread. Calls still in flight reject. */
+    close(): Promise<void>;
+}
+/** The whole body `url` answers with, or a throw saying why it didn't come. */
+export declare function fetchWhole(url: string): Promise<Uint8Array>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAOA,OAAO,EAAkB,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAG7D,OAAO,KAAK,EACR,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,QAAQ,EACX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAiCvD,8GAA8G;AAC9G,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,qBAAa,WAAW;;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAkGpC,4EAA4E;gBAChE,MAAM,EAAE,MAAM;IAiB1B,wEAAwE;IACxE,IAAI,OAAO,IAAI,QAAQ,GAAG,SAAS,CAElC;IAED;;;OAGG;IACH,IAAI,YAAY,IAAI,UAAU,GAAG,SAAS,CAEzC;IAED;;;;OAIG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;;OAKG;IACH,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED;;;;;OAKG;IACH,IAAI,YAAY,IAAI,YAAY,GAAG,SAAS,CAE3C;IAED;;;;;;OAMG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMtD;;;;;;;;OAQG;IACH,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAI5B;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAUjG;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAYpD;;;;;;;;;OASG;IACG,iBAAiB,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC;IAcrE;;;;;;;OAOG;IACG,uBAAuB,IAAI,OAAO,CAAC,wBAAwB,CAAC;IAkBlE;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC;IAIxD;;;;;;;;OAQG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAiB/E;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAI/B;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;IAIpC;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAIjD;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAI/B,iFAAiF;IACjF,aAAa,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,yEAAyE;IACnE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAiD/B;AA6DD,+EAA+E;AAC/E,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAIjE"}