@vedivad/typst-web-service 0.6.0 → 0.7.1

package/dist/index.d.ts

@@ -20,7 +20,7 @@ interface TypstAnalyzerOptions {
     /**
      * Explicit Worker instance. When omitted, an inlined blob worker is created automatically.
      * Use this for Vite apps:
-     *   `new TypstAnalyzer({ worker: new Worker(new URL('typst-web-service/analyzer-worker', import.meta.url), { type: 'module' }) })`
+     *   `await TypstAnalyzer.create({ worker: new Worker(new URL('typst-web-service/analyzer-worker', import.meta.url), { type: 'module' }) })`
      */
     worker?: Worker;
     /**
@@ -37,27 +37,25 @@ interface TypstAnalyzerOptions {
  * content changes, and receive diagnostics via `onDiagnostics()` listeners
  * whenever tinymist publishes them.
  *
- *   const analyzer = new TypstAnalyzer({ wasmUrl: '...' });
+ *   const analyzer = await TypstAnalyzer.create({ wasmUrl: '...' });
  *   analyzer.onDiagnostics((uri, diags) => { ... });
  */
 declare class TypstAnalyzer {
-    readonly ready: Promise<void>;
     private idCounter;
     private versionCounter;
     private worker;
     private openedUris;
     private diagnosticsListeners;
-    private latestDiagnosticsByUri;
-    constructor(options: TypstAnalyzerOptions);
+    private constructor();
+    static create(options: TypstAnalyzerOptions): Promise<TypstAnalyzer>;
     /**
      * Register a listener for push-based diagnostics.
      * Returns an unsubscribe function.
      */
     onDiagnostics(listener: DiagnosticsListener): () => void;
-    /** Returns the latest pushed diagnostics for a URI, if available. */
-    getLatestDiagnostics(uri: string): LspDiagnostic[] | undefined;
     private rpc;
     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.
@@ -68,6 +66,78 @@ declare class TypstAnalyzer {
     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.
+     */
+    subscribe(path: string, listener: DiagnosticsSubscriber): () => 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.
+     */
+    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>;
+    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;
+}
+
+declare function normalizeUntitledUri(uri: string): string;
+declare function normalizePath(path: string): string;
+declare function normalizeRoot(rootPath: string): string;
+
 /** Source range for a diagnostic. All values are 0-indexed. */
 interface DiagnosticRange {
     startLine: number;
@@ -92,7 +162,7 @@ interface TypstCompilerOptions {
     /**
      * Explicit Worker instance. When omitted, an inlined blob worker is created automatically.
      * Use this for Vite apps to get proper source maps:
-     *   `new TypstCompiler({ worker: new Worker(new URL('typst-web-service/worker', import.meta.url)) })`
+     *   `await TypstCompiler.create({ worker: new Worker(new URL('typst-web-service/worker', import.meta.url)) })`
      */
     worker?: Worker;
     /**
@@ -114,18 +184,18 @@ interface TypstCompilerOptions {
  * Manages a Typst compiler worker. Create one instance and share it across
  * all extensions (linter, autocomplete, preview, etc.).
  *
- *   new TypstCompiler()                                   // blob worker, defaults
- *   new TypstCompiler({ wasmUrl: '...' })                 // blob worker, custom WASM
- *   new TypstCompiler({ worker: myWorker })               // explicit Worker (Vite)
- *   new TypstCompiler({ worker: myWorker, fonts: [...] }) // explicit Worker + options
+ *   await TypstCompiler.create()                                   // blob worker, defaults
+ *   await TypstCompiler.create({ wasmUrl: '...' })                 // blob worker, custom WASM
+ *   await TypstCompiler.create({ worker: myWorker })               // explicit Worker (Vite)
+ *   await TypstCompiler.create({ worker: myWorker, fonts: [...] }) // explicit Worker + options
  */
 declare class TypstCompiler {
-    readonly ready: Promise<void>;
     private idCounter;
     private worker;
     /** The most recent vector artifact from a compile, if any. */
     lastVector?: Uint8Array;
-    constructor(options?: TypstCompilerOptions);
+    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. */
@@ -133,79 +203,6 @@ declare class TypstCompiler {
     destroy(): void;
 }
 
-type DiagnosticsSubscriber = (diagnostics: LspDiagnostic[]) => void;
-interface AnalyzerSessionOptions {
-    analyzer: Pick<TypstAnalyzer, "ready" | "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", source, files);
- */
-declare class AnalyzerSession {
-    readonly ready: Promise<void>;
-    private readonly analyzer;
-    private readonly rootPath;
-    private readonly entryPath;
-    private readonly syncedFiles;
-    private queue;
-    private syncRevision;
-    private readonly listenersByUri;
-    private readonly diagnosticsByUri;
-    private readonly diagnosticsHashByUri;
-    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. Replays cached diagnostics immediately.
-     */
-    subscribe(path: string, listener: DiagnosticsSubscriber): () => void;
-    /**
-     * Sync all project files with the analyzer, then notify it of the active file change.
-     * Diagnostics will arrive asynchronously via subscribers registered with `subscribe()`.
-     */
-    sync(path: string, content: string, files: Record<string, string>): Promise<void>;
-    /**
-     * Sync files, then compile with the provided compiler.
-     * Diagnostics come from the analyzer (push-based); the compiler provides preview artifacts.
-     */
-    syncAndCompile(path: string, content: string, files: Record<string, string>, compiler: TypstCompiler, onCompile?: (result: CompileResult) => void, signal?: AbortSignal): Promise<void>;
-    /**
-     * Sync files and request completions at the given position.
-     * Returns the raw LSP CompletionList/CompletionItem[] from tinymist.
-     */
-    completion(path: string, content: 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, content: string, files: Record<string, string>, line: number, character: number): Promise<unknown>;
-    destroy(): void;
-    /**
-     * Sync a single file with the analyzer.
-     * @param forceOpen - Always use didOpen (triggers tinymist diagnostics for the active file).
-     */
-    private syncFile;
-    private orderedPaths;
-    private enqueue;
-}
-
-declare function normalizeUntitledUri(uri: string): string;
-declare function normalizePath(path: string): string;
-declare function normalizeRoot(rootPath: string): string;
-
 interface FormatConfig {
     /** Number of spaces per indentation level. Default: 2 */
     tab_spaces?: number;
@@ -235,12 +232,13 @@ interface FormatRangeResult {
  * The WASM module is loaded lazily on first format call.
  * Requires a bundler that supports WASM imports (e.g. Vite, webpack).
  *
- *   const formatter = new TypstFormatter({ tab_spaces: 2, max_width: 80 });
+ *   const formatter = TypstFormatter.create({ tab_spaces: 2, max_width: 80 });
  *   const formatted = await formatter.format(source);
  */
 declare class TypstFormatter {
     private config;
-    constructor(config?: FormatConfig);
+    private constructor();
+    static create(config?: FormatConfig): TypstFormatter;
     /** Format an entire Typst source string. */
     format(source: string): Promise<string>;
     /** Format a range within a Typst source string. Indices are UTF-16 code units. */
@@ -256,14 +254,15 @@ interface TypstRendererOptions {
  *
  * The renderer WASM module is loaded lazily on first use.
  *
- *   const renderer = new TypstRenderer();
+ *   const renderer = TypstRenderer.create();
  *   const svg = await renderer.renderSvg(vector);
  */
 declare class TypstRenderer {
     #private;
     private wasmUrl;
     private instance;
-    constructor(options?: TypstRendererOptions);
+    private constructor();
+    static create(options?: TypstRendererOptions): TypstRenderer;
     private getInstance;
     /** Free the underlying WASM renderer instance. */
     destroy(): Promise<void>;