@vedivad/typst-web-service 0.7.12 → 0.8.0

package/dist/index.d.ts

@@ -1,21 +1,3 @@
-/** LSP Diagnostic as returned by tinymist. */
-interface LspDiagnostic {
-    range: {
-        start: {
-            line: number;
-            character: number;
-        };
-        end: {
-            line: number;
-            character: number;
-        };
-    };
-    severity?: number;
-    message: string;
-    source?: string;
-}
-
-type DiagnosticsListener = (uri: string, diagnostics: LspDiagnostic[]) => void;
 interface TypstAnalyzerOptions {
     /**
      * Explicit Worker instance. When omitted, an inlined blob worker is created automatically.
@@ -31,106 +13,53 @@ interface TypstAnalyzerOptions {
 }
 /**
  * Manages a tinymist language server in a Web Worker. Provides LSP-based
- * diagnostics, completion, and hover for Typst documents.
- *
- * Diagnostics are push-based: call `didChange()` to notify the analyzer of
- * content changes, and receive diagnostics via `onDiagnostics()` listeners
- * whenever tinymist publishes them.
+ * completion and hover for Typst documents.
  *
  *   const analyzer = await TypstAnalyzer.create({ wasmUrl: '...' });
- *   analyzer.onDiagnostics((uri, diags) => { ... });
  */
 declare class TypstAnalyzer {
     private readonly proxy;
     private readonly worker;
     private versionCounter;
     private openedUris;
-    private diagnosticsListeners;
     private constructor();
     static create(options: TypstAnalyzerOptions): Promise<TypstAnalyzer>;
-    /**
-     * Register a listener for push-based diagnostics.
-     * Returns an unsubscribe function.
-     */
-    onDiagnostics(listener: DiagnosticsListener): () => void;
     didOpen(uri: string, content: string): Promise<void>;
     didClose(uri: string): Promise<void>;
     /**
      * Notify the analyzer that a document has changed.
-     * Diagnostics will arrive asynchronously via `onDiagnostics()` listeners.
      */
     didChange(uri: string, content: string): Promise<void>;
-    completion(uri: string, line: number, character: number): Promise<unknown>;
-    hover(uri: string, line: number, character: number): Promise<unknown>;
-    destroy(): void;
-}
-
-type DiagnosticsSubscriber = (diagnostics: LspDiagnostic[]) => void;
-interface AnalyzerSessionOptions {
-    analyzer: Pick<TypstAnalyzer, "didOpen" | "didChange" | "completion" | "hover" | "onDiagnostics">;
-    /** Project root used to build stable in-memory analyzer URIs. Default: "/project". */
-    rootPath?: string;
-    /** Entry file path within the project. Synced last to ensure dependencies load first. Default: "/main.typ". */
-    entryPath?: string;
-}
-/**
- * Synchronizes an in-memory Typst project with a TypstAnalyzer.
- * Handles multi-file ordering, request queueing, and diagnostic subscriptions.
- *
- * Diagnostics arrive via the analyzer's push mechanism and are forwarded
- * to subscribers registered with `subscribe()`.
- *
- *   const session = new AnalyzerSession({ analyzer });
- *   session.subscribe("/main.typ", (diags) => { ... });
- *   await session.sync("/main.typ", files);
- */
-declare class AnalyzerSession {
-    private readonly analyzer;
-    private readonly rootPath;
-    private readonly entryPath;
-    private readonly syncedFiles;
-    private queue;
-    private readonly listenersByUri;
-    /** Last push received per URI. Replayed on subscribe() so tab-back shows correct diagnostics instantly. */
-    private readonly diagnosticsCache;
-    private readonly unsubscribeAnalyzer;
-    constructor(options: AnalyzerSessionOptions);
-    /** Build a tinymist URI from a project-relative path. */
-    toUri(path: string): string;
     /**
-     * Subscribe to push-based diagnostics for a file path.
-     * Returns an unsubscribe function.
+     * Batch document changes. Splits inputs into opens (first-time URIs) and
+     * changes (already-open URIs) and sends them in a single worker roundtrip.
      */
-    subscribe(path: string, listener: DiagnosticsSubscriber): () => void;
+    didChangeMany(docs: Record<string, string>): Promise<void>;
     /**
-     * Sync all project files with the analyzer.
-     * `files` must include the active file's current content under `path`.
-     *
-     * If the active file's content hasn't changed since the last sync, a
-     * lightweight hover is triggered to ensure the analyzer re-analyzes with
-     * the current project state and publishes fresh diagnostics.
+     * Batch document closes. Filters to currently-open URIs and sends the set
+     * in a single worker roundtrip.
      */
-    sync(path: string, files: Record<string, string>): Promise<void>;
-    /**
-     * Sync files and request completions at the given position.
-     * Returns the raw LSP CompletionList/CompletionItem[] from tinymist.
-     */
-    completion(path: string, files: Record<string, string>, line: number, character: number): Promise<unknown>;
-    /**
-     * Sync files and request hover info at the given position.
-     * Returns the raw LSP Hover result from tinymist.
-     */
-    hover(path: string, files: Record<string, string>, line: number, character: number): Promise<unknown>;
+    didCloseMany(uris: string[]): Promise<void>;
+    completion(uri: string, line: number, character: number): Promise<unknown>;
+    hover(uri: string, line: number, character: number): Promise<unknown>;
     destroy(): void;
-    /**
-     * Sync all project files: dependencies first, active file last.
-     * Returns whether the active file's content was actually sent to the analyzer.
-     */
-    private syncFiles;
-    /** Sync a single file. Returns true if content was sent to the analyzer. */
-    private syncFile;
-    private orderedPaths;
-    private enqueue;
+}
+
+/** LSP Diagnostic as returned by tinymist. */
+interface LspDiagnostic {
+    range: {
+        start: {
+            line: number;
+            character: number;
+        };
+        end: {
+            line: number;
+            character: number;
+        };
+    };
+    severity?: number;
+    message: string;
+    source?: string;
 }
 
 declare function normalizeUntitledUri(uri: string): string;
@@ -196,25 +125,30 @@ declare class TypstCompiler {
     lastVector?: Uint8Array;
     private constructor();
     static create(options?: TypstCompilerOptions): Promise<TypstCompiler>;
-    /** Compile a single source string (treated as /main.typ) or a map of files. */
-    compile(source: string | Record<string, string>): Promise<CompileResult>;
-    /** Compile to PDF from a single source string (treated as /main.typ) or a map of files. */
-    compilePdf(source: string | Record<string, string>): Promise<Uint8Array>;
-    /** Add or overwrite a text source file. */
-    addSource(path: string, source: string): Promise<void>;
-    /** Add or overwrite an in-memory shadow file (text or binary). */
-    mapShadow(path: string, content: Uint8Array): Promise<void>;
-    /** Remove an in-memory shadow file by path. */
-    unmapShadow(path: string): Promise<void>;
     /**
-     * Clear all shadow files held by the compiler.
-     * Note: this also clears files previously added via addSource in the compiler runtime.
+     * Compile. Pass a source string (written to the entry path) or a map of
+     * files to register before compiling; omit to compile whatever is currently
+     * in the VFS (populated via setText/setBinary/setJson/setMany).
+     * Defaults to compiling "/main.typ"; override with `entry`.
+     */
+    compile(source?: string | Record<string, string>, entry?: string): Promise<CompileResult>;
+    /**
+     * Compile to PDF. Pass a source string (written to the entry path) or a map
+     * of files to register before compiling; omit to compile whatever is
+     * currently in the VFS (populated via setText/setBinary/setJson/setMany).
+     * Defaults to compiling "/main.typ"; override with `entry`.
      */
-    resetShadow(): Promise<void>;
+    compilePdf(source?: string | Record<string, string>, entry?: string): Promise<Uint8Array>;
     /** Add or overwrite a text file in the virtual compiler filesystem. */
     setText(path: string, source: string): Promise<void>;
     /** Add or overwrite a JSON file in the virtual compiler filesystem. */
     setJson(path: string, value: unknown, replacer?: (this: unknown, key: string, value: unknown) => unknown, space?: string | number): Promise<void>;
+    /**
+     * Add or overwrite multiple files in the virtual compiler filesystem in a
+     * single worker roundtrip. Strings are UTF-8 encoded; Uint8Arrays are passed
+     * through.
+     */
+    setMany(files: Record<string, string | Uint8Array>): Promise<void>;
     /** Add or overwrite a binary file in the virtual compiler filesystem. */
     setBinary(path: string, content: ArrayBuffer | ArrayBufferView): Promise<void>;
     /** Remove a file from the virtual compiler filesystem. */
@@ -266,6 +200,86 @@ declare class TypstFormatter {
     formatRange(source: string, start: number, end: number): Promise<FormatRangeResult>;
 }
 
+interface TypstProjectOptions {
+    compiler: TypstCompiler;
+    /**
+     * Optional analyzer. When provided, text file operations also sync with the
+     * analyzer so completions / hover reflect the current state.
+     */
+    analyzer?: TypstAnalyzer;
+    /** Default entry file path. Default: "/main.typ". */
+    entry?: string;
+    /**
+     * Project root used to build stable analyzer URIs. Default: "/project".
+     * URIs are formed as `untitled:<root-without-leading-slash><path>` — so
+     * `/main.typ` becomes `untitled:project/main.typ`.
+     */
+    rootPath?: string;
+}
+/**
+ * Coordinates a compiler + analyzer pair for multi-file Typst projects.
+ *
+ * Owns the project's virtual filesystem state. Editors push incremental
+ * `setText` updates as the user types; the project mirrors those edits to
+ * both the compiler's shadow VFS and the analyzer's open-document set, then
+ * compiles or services LSP requests against the current state.
+ *
+ *   const project = new TypstProject({ compiler, analyzer });
+ *   await project.setMany({ "/main.typ": "...", "/utils.typ": "..." });
+ *   const result = await project.compile();
+ */
+declare class TypstProject {
+    private readonly compiler;
+    private readonly analyzer?;
+    private readonly rootPath;
+    private readonly trackedTextPaths;
+    /** Last content written via setText/setMany, per path. Used to skip redundant writes to compiler + analyzer. */
+    private readonly lastSyncedContent;
+    private _entry;
+    constructor(options: TypstProjectOptions);
+    /** Current entry file path. */
+    get entry(): string;
+    /** Whether an analyzer is attached. */
+    get hasAnalyzer(): boolean;
+    /** Change the sticky entry file used by subsequent compile() calls. */
+    setEntry(path: string): void;
+    /**
+     * Add or overwrite a text file. Goes to the compiler's VFS and, when an
+     * analyzer is attached, to the analyzer as a document change. Redundant
+     * calls with unchanged content are skipped.
+     */
+    setText(path: string, content: string): Promise<void>;
+    /**
+     * Add or overwrite a JSON file. Compiler-only — the analyzer does not track
+     * data files.
+     */
+    setJson(path: string, value: unknown): Promise<void>;
+    /** Add or overwrite a binary file. Compiler-only. */
+    setBinary(path: string, content: ArrayBuffer | ArrayBufferView): Promise<void>;
+    /**
+     * Batch set multiple files. Strings route to both compiler and analyzer;
+     * Uint8Array entries go to the compiler only.
+     */
+    setMany(files: Record<string, string | Uint8Array>): Promise<void>;
+    /**
+     * Remove a file. Always removed from the compiler's VFS; also closed on the
+     * analyzer when it was previously tracked as text.
+     */
+    remove(path: string): Promise<void>;
+    /** Clear all files from both compiler VFS and analyzer document set. */
+    clear(): Promise<void>;
+    /** Compile the current VFS state using the sticky entry. */
+    compile(): Promise<CompileResult>;
+    /** Compile the current VFS state to PDF using the sticky entry. */
+    compilePdf(): Promise<Uint8Array>;
+    private requireAnalyzer;
+    /** Request completions at the given position. Throws when no analyzer is attached. */
+    completion(path: string, line: number, character: number): Promise<unknown>;
+    /** Request hover info at the given position. Throws when no analyzer is attached. */
+    hover(path: string, line: number, character: number): Promise<unknown>;
+    private toUri;
+}
+
 interface TypstRendererOptions {
     /** URL to the typst-ts-renderer WASM binary. Defaults to jsDelivr CDN. */
     wasmUrl?: string;
@@ -291,4 +305,4 @@ declare class TypstRenderer {
     renderSvg(vector: Uint8Array): Promise<string>;
 }
 
-export { AnalyzerSession, type AnalyzerSessionOptions, type CompileResult, type DiagnosticMessage, type DiagnosticRange, type DiagnosticsSubscriber, type FormatConfig, type FormatRangeResult, type LspDiagnostic, TypstAnalyzer, type TypstAnalyzerOptions, TypstCompiler, type TypstCompilerOptions, TypstFormatter, TypstRenderer, type TypstRendererOptions, normalizePath, normalizeRoot, normalizeUntitledUri };
+export { type CompileResult, type DiagnosticMessage, type DiagnosticRange, type FormatConfig, type FormatRangeResult, type LspDiagnostic, TypstAnalyzer, type TypstAnalyzerOptions, TypstCompiler, type TypstCompilerOptions, TypstFormatter, TypstProject, type TypstProjectOptions, TypstRenderer, normalizePath, normalizeRoot, normalizeUntitledUri };