@observablehq/notebook-kit 1.0.1 → 1.1.0-rc.1

package/dist/src/javascript/transpile.test.js

@@ -6,6 +6,13 @@ it("transpiles JavaScript expressions", () => {
     expect(transpile("await z", "js")).toMatchSnapshot();
     expect(transpile("display(1), display(2)", "js")).toMatchSnapshot();
 });
+it("transpiles empty cells", () => {
+    expect(transpile("", "js")).toMatchSnapshot();
+    expect(transpile("", "md")).toMatchSnapshot();
+    expect(transpile("", "html")).toMatchSnapshot();
+    expect(transpile("", "tex")).toMatchSnapshot();
+    expect(transpile("", "sql")).toMatchSnapshot();
+});
 it("transpiles JavaScript programs", () => {
     expect(transpile("const x = 1, y = 2;", "js")).toMatchSnapshot();
     expect(transpile("x + y;", "js")).toMatchSnapshot();
@@ -21,6 +28,15 @@ it("transpiles dynamic npm: imports", () => {
 });
 it("transpiles static observable: imports", () => {
     expect(transpile('import {Scrubber} from "observable:@mbostock/scrubber";', "js")).toMatchSnapshot();
+    expect(transpile('import {viewof$rotation} from "observable:@rreusser/drawing-3d-objects-with-svg";', "js")).toMatchSnapshot();
+});
+it("transpiles static imports with {type: 'observable'}", () => {
+    expect(transpile('import {Scrubber} from "https://api.observablehq.com/@mbostock/scrubber.js?v=4" with {type: "observable"};', "js")).toMatchSnapshot();
+    expect(transpile('import {viewof$rotation} from "https://api.observablehq.com/@rreusser/drawing-3d-objects-with-svg.js?v=4" with {type: "observable"};', "js")).toMatchSnapshot();
+});
+it("transpiles Observable JavaScript imports", () => {
+    expect(transpile('import {figure, viewof rotation} from "@rreusser/drawing-3d-objects-with-svg"', "ojs")).toMatchSnapshot();
+    expect(transpile('import {figure, viewof rotation as rot} from "@rreusser/drawing-3d-objects-with-svg"', "ojs")).toMatchSnapshot();
 });
 it("transpiles import.meta.resolve", () => {
     expect(transpile('import.meta.resolve("npm:d3")', "js")).toMatchSnapshot();

package/dist/src/lib/error.d.ts

@@ -0,0 +1,6 @@
+export declare function isEnoent(error: unknown): error is Error & {
+    code: "ENOENT";
+};
+export declare function isSystemError(error: unknown): error is Error & {
+    code: string;
+};

package/dist/src/lib/error.js

@@ -0,0 +1,6 @@
+export function isEnoent(error) {
+    return isSystemError(error) && error.code === "ENOENT";
+}
+export function isSystemError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/src/lib/notebook.d.ts

@@ -24,12 +24,22 @@ export interface CellSpec {
     mode?: "js" | "ojs" | "md" | "html" | "tex" | "dot" | "sql";
     /** if true, the editor will stay open when not focused; defaults to false */
     pinned?: boolean;
+    /** if true, implicit display will be suppressed; defaults to false */
+    hidden?: boolean;
+    /** if present, exposes the cell’s value to the rest of the notebook */
+    output?: string;
+    /** for SQL cells, the database to query; use var:<name> to refer to a variable */
+    database?: string;
+    /** for SQL cells, the oldest allowable age of the cached query result */
+    since?: Date | string | number;
 }
 export interface Cell extends CellSpec {
     value: NonNullable<CellSpec["value"]>;
     mode: NonNullable<CellSpec["mode"]>;
     pinned: NonNullable<CellSpec["pinned"]>;
+    hidden: NonNullable<CellSpec["hidden"]>;
+    since?: Date;
 }
 export declare function toNotebook({ cells, title, theme, readOnly }: NotebookSpec): Notebook;
-export declare function toCell({ id, value, mode, pinned }: CellSpec): Cell;
+export declare function toCell({ id, value, mode, pinned, hidden, output, database, since }: CellSpec): Cell;
 export declare function defaultPinned(mode: Cell["mode"]): boolean;

package/dist/src/lib/notebook.js

@@ -6,14 +6,21 @@ export function toNotebook({ cells = [], title = "Untitled", theme = "air", read
         readOnly
     };
 }
-export function toCell({ id, value = "", mode = "js", pinned = defaultPinned(mode) }) {
+export function toCell({ id, value = "", mode = "js", pinned = defaultPinned(mode), hidden = false, output, database = mode === "sql" ? "var:db" : undefined, since }) {
     return {
         id,
         value,
         mode,
-        pinned
+        pinned,
+        hidden,
+        output,
+        database: mode === "sql" ? database : undefined,
+        since: since !== undefined ? asDate(since) : undefined
     };
 }
+function asDate(date) {
+    return date instanceof Date ? date : new Date(date);
+}
 export function defaultPinned(mode) {
-    return mode === "js" || mode === "ojs";
+    return mode === "js" || mode === "sql" || mode === "ojs";
 }

package/dist/src/lib/notebook.test.js

@@ -13,7 +13,11 @@ test("converts a cell spec to a cell", () => {
         id: 1,
         value: "",
         mode: "js",
-        pinned: true
+        pinned: true,
+        hidden: false,
+        output: undefined,
+        database: undefined,
+        since: undefined
     });
 });
 test("computes an appropriate default pinned based on the cell mode", () => {
@@ -21,6 +25,10 @@ test("computes an appropriate default pinned based on the cell mode", () => {
         id: 1,
         value: "",
         mode: "md",
-        pinned: false
+        pinned: false,
+        hidden: false,
+        output: undefined,
+        database: undefined,
+        since: undefined
     });
 });

package/dist/src/lib/serialize.d.ts

@@ -1,5 +1,7 @@
 import type { Notebook } from "./notebook.js";
-export declare function serialize(notebook: Notebook): string;
+export declare function serialize(notebook: Notebook, { document }?: {
+    document?: Document | undefined;
+}): string;
 export declare function deserialize(data: string, { parser }?: {
     parser?: DOMParser | undefined;
 }): Notebook;

package/dist/src/lib/serialize.js

@@ -1,6 +1,6 @@
 import { toNotebook } from "./notebook.js";
 import { isEmpty } from "./text.js";
-export function serialize(notebook) {
+export function serialize(notebook, { document = globalThis.document } = {}) {
     const _notebook = document.createElement("notebook");
     _notebook.setAttribute("theme", notebook.theme);
     if (notebook.readOnly)
@@ -17,6 +17,12 @@ export function serialize(notebook) {
         _cell.textContent = indent(cell.value.replace(/<(?=\\*\/script(\s|>))/gi, "<\\"));
         if (cell.pinned)
             _cell.setAttribute("pinned", "");
+        if (cell.hidden)
+            _cell.setAttribute("hidden", "");
+        if (cell.database)
+            _cell.setAttribute("database", cell.database);
+        if (cell.output)
+            _cell.setAttribute("output", cell.output);
         _notebook.appendChild(_cell);
     }
     _notebook.appendChild(document.createTextNode("\n"));
@@ -37,10 +43,13 @@ export function deserialize(data, { parser = new DOMParser() } = {}) {
         else if (id > maxCellId)
             maxCellId = id;
         cellIds.add(id);
-        const pinned = cell.hasAttribute("pinned");
-        const value = dedent(cell.textContent?.replace(/<\\(?=\\*\/script(\s|>))/gi, "<") ?? "");
         const mode = deserializeMode(cell.getAttribute("type"));
-        return { id, pinned, mode, value };
+        const value = dedent(cell.textContent?.replace(/<\\(?=\\*\/script(\s|>))/gi, "<") ?? "");
+        const pinned = cell.hasAttribute("pinned");
+        const hidden = cell.hasAttribute("hidden");
+        const output = cell.getAttribute("output") ?? undefined;
+        const database = cell.getAttribute("database") ?? undefined;
+        return { id, mode, value, pinned, hidden, output, database };
     });
     return toNotebook({ title, theme, readOnly, cells });
 }

package/dist/src/lib/serialize.test.js

@@ -1,7 +1,14 @@
-// @vitest-environment jsdom
+import { JSDOM } from "jsdom";
 import { assert, test } from "vitest";
 import { toNotebook } from "./notebook.js";
-import { deserialize, serialize } from "./serialize.js";
+import { deserialize as _deserialize, serialize as _serialize } from "./serialize.js";
+const { window } = new JSDOM();
+function serialize(notebook) {
+    return _serialize(notebook, { document: window.document });
+}
+function deserialize(data) {
+    return _deserialize(data, { parser: new window.DOMParser() });
+}
 test("serializes unpinned cells", () => {
     const notebook1 = toNotebook({
         cells: [
@@ -84,7 +91,7 @@ test("serialization escapes </script>, in various forms", () => {
             { id: 6, mode: "js", pinned: true, value: `'<\\/script>'` },
             { id: 7, mode: "js", pinned: true, value: `'<\\/script '` },
             { id: 8, mode: "js", pinned: true, value: `'<\\\\/SCRIPT '` },
-            { id: 9, mode: "js", pinned: true, value: `'<\\\\/sCrIpT '` },
+            { id: 9, mode: "js", pinned: true, value: `'<\\\\/sCrIpT '` }
         ]
     });
     const html = serialize(notebook1);

package/dist/src/runtime/define.d.ts

@@ -1,4 +1,4 @@
-import type { Variable, VariableDefinition } from "@observablehq/runtime";
+import type { Module, Variable, VariableDefinition } from "@observablehq/runtime";
 import type { DisplayState } from "./display.js";
 import { observe } from "./display.js";
 export type DefineState = DisplayState & {
@@ -25,4 +25,4 @@ export type Definition = {
     /** an asset mapping to apply to any autodisplayed assets (e.g., images and videos) */
     assets?: Map<string, string>;
 };
-export declare function define(state: DefineState, definition: Definition, observer?: typeof observe): void;
+export declare function define(main: Module, state: DefineState, definition: Definition, observer?: typeof observe): void;

package/dist/src/runtime/define.js

@@ -1,12 +1,12 @@
 import { clear, display, observe } from "./display.js";
-import { main } from "./index.js";
 import { input } from "./stdlib/generators/index.js";
 import { Mutator } from "./stdlib/mutable.js";
-export function define(state, definition, observer = observe) {
+export function define(main, state, definition, observer = observe) {
     const { id, body, inputs = [], outputs = [], output, autodisplay, autoview, automutable } = definition;
     const variables = state.variables;
     const v = main.variable(observer(state, definition), { shadow: {} });
     const vid = output ?? (outputs.length ? `cell ${id}` : null);
+    state.autoclear = true;
     if (inputs.includes("display") || inputs.includes("view")) {
         let displayVersion = -1; // the variable._version of currently-displayed values
         const vd = new v.constructor(2, v._module);

package/dist/src/runtime/display.d.ts

@@ -2,6 +2,8 @@ import type { Definition } from "./define.js";
 export type DisplayState = {
     /** the HTML element in which to render this cell’s display */
     root: HTMLDivElement;
+    /** whether to clear on fulfilled */
+    autoclear?: boolean;
     /** for inspected values, any expanded paths; see getExpanded */
     expanded: (number[][] | undefined)[];
 };

package/dist/src/runtime/display.js

@@ -28,6 +28,7 @@ function isDisplayable(value, root) {
         (!value.parentNode || root.contains(value)));
 }
 export function clear(state) {
+    state.autoclear = false;
     state.expanded = Array.from(state.root.childNodes, getExpanded);
     while (state.root.lastChild)
         state.root.lastChild.remove();
@@ -44,11 +45,14 @@ export function observe(state, { autodisplay, assets }) {
         },
         fulfilled(value) {
             if (autodisplay) {
-                clear(state);
                 if (assets && value instanceof Element)
                     mapAssets(value, assets);
+                clear(state);
                 display(state, value);
             }
+            else if (state.autoclear) {
+                clear(state);
+            }
         },
         rejected(error) {
             console.error(error);

package/dist/src/runtime/index.d.ts

@@ -1,11 +1,110 @@
 import type { Module } from "@observablehq/runtime";
 import { Runtime } from "@observablehq/runtime";
+import type { DefineState, Definition } from "./define.js";
+import type { observe } from "./display.js";
 import { fileAttachments } from "./stdlib/fileAttachment.js";
-export * from "./define.js";
+export type { DefineState, Definition } from "./define.js";
 export * from "./display.js";
 export * from "./inspect.js";
 export * from "./stdlib/index.js";
+export type * from "./stdlib/databaseClient.js";
+export { DatabaseClient } from "./stdlib/databaseClient.js";
+export type * from "./stdlib/fileAttachment.js";
+export { FileAttachment, registerFile } from "./stdlib/fileAttachment.js";
+export declare class NotebookRuntime {
+    readonly runtime: Runtime & {
+        fileAttachments: typeof fileAttachments;
+    };
+    readonly main: Module;
+    constructor(builtins?: {
+        aapl: () => Promise<any>;
+        alphabet: () => Promise<any>;
+        cars: () => Promise<any>;
+        citywages: () => Promise<any>;
+        diamonds: () => Promise<any>;
+        flare: () => Promise<any>;
+        industries: () => Promise<any>;
+        miserables: () => Promise<any>;
+        olympians: () => Promise<any>;
+        penguins: () => Promise<any>;
+        pizza: () => Promise<any>;
+        weather: () => Promise<any>;
+        _: () => Promise<any>;
+        aq: () => Promise<any>;
+        Arrow: () => Promise<any>;
+        d3: () => Promise<any>;
+        dot: () => Promise<import("./stdlib/template.js").RawTemplateRenderer>;
+        duckdb: () => Promise<any>;
+        DuckDBClient: () => Promise<typeof import("./stdlib/duckdb.js").DuckDBClient>;
+        echarts: () => Promise<any>;
+        htl: () => Promise<any>;
+        html: () => Promise<any>;
+        svg: () => Promise<any>;
+        Inputs: () => Promise<typeof import("./stdlib/inputs.js")>;
+        L: () => Promise<typeof import("./stdlib/leaflet.js")>;
+        mapboxgl: () => Promise<any>;
+        md: () => Promise<import("./stdlib/template.js").TemplateRenderer>;
+        mermaid: () => Promise<import("./stdlib/template.js").AsyncRawTemplateRenderer>;
+        Plot: () => Promise<any>;
+        React: () => Promise<any>;
+        ReactDOM: () => Promise<any>;
+        tex: () => Promise<import("./stdlib/template.js").RawTemplateRenderer & {
+            options: (options?: any) => import("./stdlib/template.js").RawTemplateRenderer;
+            block: import("./stdlib/template.js").RawTemplateRenderer;
+        }>;
+        topojson: () => Promise<any>;
+        vl: () => Promise<any>;
+        now: () => AsyncGenerator<number, void, unknown>;
+        width: () => AsyncGenerator<number, void, unknown>;
+        DatabaseClient: () => {
+            (name: string, options?: import("./stdlib/databaseClient.js").QueryOptionsSpec): import("./stdlib/databaseClient.js").DatabaseClient;
+            hash: (strings: string[], ...params: unknown[]) => Promise<string>;
+            revive: ({ rows, schema, date, ...meta }: import("../databases/index.js").SerializableQueryResult) => import("./stdlib/databaseClient.js").QueryResult;
+            prototype: {
+                readonly name: string;
+                readonly options: import("./stdlib/databaseClient.js").QueryOptions;
+                sql(strings: string[], ...params: import("./stdlib/databaseClient.js").QueryParam[]): Promise<import("./stdlib/databaseClient.js").QueryResult>;
+            };
+        };
+        FileAttachment: () => {
+            (name: string, base?: string): import("./stdlib/fileAttachment.js").FileAttachment;
+            prototype: {
+                href: string;
+                name: string;
+                mimeType: string;
+                lastModified: number | undefined;
+                size: number | undefined;
+                url(): Promise<string>;
+                blob(): Promise<Blob>;
+                arrayBuffer(): Promise<ArrayBuffer>;
+                text(encoding?: string): Promise<string>;
+                json(): Promise<any>;
+                stream(): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+                dsv({ delimiter, array, typed }?: {
+                    delimiter?: string | undefined;
+                    array?: boolean | undefined;
+                    typed?: boolean | undefined;
+                }): Promise<import("./stdlib/fileAttachment.js").DsvResult>;
+                csv(options?: Omit<import("./stdlib/fileAttachment.js").DsvOptions, "delimiter">): Promise<import("./stdlib/fileAttachment.js").DsvResult>;
+                tsv(options?: Omit<import("./stdlib/fileAttachment.js").DsvOptions, "delimiter">): Promise<import("./stdlib/fileAttachment.js").DsvResult>;
+                image(props?: Partial<HTMLImageElement>): Promise<HTMLImageElement>;
+                arrow(): Promise<any>;
+                arquero(options?: any): Promise<any>;
+                parquet(): Promise<any>;
+                xml(mimeType?: DOMParserSupportedType): Promise<Document>;
+                html(): Promise<Document>;
+            };
+        };
+        Generators: () => typeof import("./stdlib/generators/index.js");
+        Mutable: () => typeof import("./stdlib/mutable.js").Mutable;
+        DOM: () => typeof import("./stdlib/dom/index.js");
+        require: () => typeof import("./stdlib/require.js").require;
+        __ojs_observer: () => () => import("./stdlib/observer.js").Observer;
+    });
+    define(state: DefineState, definition: Definition, observer?: typeof observe): void;
+}
 export declare const runtime: Runtime & {
     fileAttachments: typeof fileAttachments;
 };
 export declare const main: Module;
+export declare const define: (state: DefineState, definition: Definition, observer?: typeof observe) => void;

package/dist/src/runtime/index.js

@@ -1,12 +1,38 @@
 import { Runtime } from "@observablehq/runtime";
+import { define as _define } from "./define.js";
 import { fileAttachments } from "./stdlib/fileAttachment.js";
 import { library } from "./stdlib/index.js";
-export * from "./define.js";
 export * from "./display.js";
 export * from "./inspect.js";
 export * from "./stdlib/index.js";
-export const runtime = Object.assign(new Runtime({ ...library, __ojs_runtime: () => runtime }), { fileAttachments });
-export const main = runtime.main = runtime.module();
+export { DatabaseClient } from "./stdlib/databaseClient.js";
+export { FileAttachment, registerFile } from "./stdlib/fileAttachment.js";
+export class NotebookRuntime {
+    constructor(builtins = library) {
+        Object.defineProperty(this, "runtime", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "main", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        const runtime = new Runtime({ ...builtins, __ojs_runtime: () => runtime });
+        this.runtime = Object.assign(runtime, { fileAttachments });
+        this.main = runtime.module();
+    }
+    define(state, definition, observer) {
+        _define(this.main, state, definition, observer);
+    }
+}
+const defaultNotebook = new NotebookRuntime();
+export const runtime = defaultNotebook.runtime;
+export const main = defaultNotebook.main;
+export const define = defaultNotebook.define.bind(defaultNotebook);
 main.constructor.prototype.defines = function (name) {
     return (this._scope.has(name) ||
         this._builtins.has(name) ||

package/dist/src/runtime/stdlib/databaseClient.d.ts

@@ -0,0 +1,46 @@
+import type { SerializableQueryResult } from "../../databases/index.js";
+/** A serializable value that can be interpolated into a query. */
+export type QueryParam = any;
+/** @see https://observablehq.com/@observablehq/database-client-specification#%C2%A71 */
+export type QueryResult = Record<string, any>[] & {
+    schema: ColumnSchema[];
+    date: Date;
+};
+/** @see https://observablehq.com/@observablehq/database-client-specification#%C2%A72.2 */
+export interface ColumnSchema {
+    /** The name of the column. */
+    name: string;
+    /** The type of the column. */
+    type: "string" | "number" | "integer" | "bigint" | "date" | "boolean" | "object" | "array" | "buffer" | "other";
+    /** If present, the nullability of the column is known. */
+    nullable?: boolean;
+}
+export interface QueryOptionsSpec {
+    /** if present, the id of the cell that owns this database client */
+    id?: number;
+    /** if present, query results are at least as fresh as the specified date */
+    since?: Date | string | number;
+}
+export interface QueryOptions extends QueryOptionsSpec {
+    since?: Date;
+}
+export interface DatabaseClient {
+    readonly name: string;
+    readonly options: QueryOptions;
+    sql(strings: string[], ...params: QueryParam[]): Promise<QueryResult>;
+}
+export declare const DatabaseClient: {
+    (name: string, options?: QueryOptionsSpec): DatabaseClient;
+    hash: typeof hash;
+    revive: typeof revive;
+    prototype: DatabaseClientImpl;
+};
+declare class DatabaseClientImpl implements DatabaseClient {
+    readonly name: string;
+    readonly options: QueryOptions;
+    constructor(name: string, options: QueryOptions);
+    sql(strings: string[], ...params: QueryParam[]): Promise<QueryResult>;
+}
+declare function hash(strings: string[], ...params: unknown[]): Promise<string>;
+declare function revive({ rows, schema, date, ...meta }: SerializableQueryResult): QueryResult;
+export {};

package/dist/src/runtime/stdlib/databaseClient.js

@@ -0,0 +1,80 @@
+export const DatabaseClient = (name, options) => {
+    if (!/^[\w-]+$/.test(name))
+        throw new Error(`invalid database: ${name}`);
+    return new DatabaseClientImpl(name, normalizeOptions(options));
+};
+function normalizeOptions({ id, since } = {}) {
+    const options = {};
+    if (id !== undefined)
+        options.id = id;
+    if (since !== undefined)
+        options.since = new Date(since);
+    return options;
+}
+class DatabaseClientImpl {
+    constructor(name, options) {
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperties(this, {
+            name: { value: name, enumerable: true },
+            options: { value: options, enumerable: true }
+        });
+    }
+    async sql(strings, ...params) {
+        const path = `.observable/cache/${this.name}-${await hash(strings, ...params)}.json`;
+        const response = await fetch(path);
+        if (!response.ok)
+            throw new Error(`failed to fetch: ${path}`);
+        return await response.json().then(revive);
+    }
+}
+async function hash(strings, ...params) {
+    const encoded = new TextEncoder().encode(JSON.stringify([strings, ...params]));
+    const buffer = await crypto.subtle.digest("SHA-256", encoded);
+    const int = new Uint8Array(buffer).reduce((i, byte) => (i << 8n) | BigInt(byte), 0n);
+    const length = 16;
+    return int.toString(36).padStart(length, "0").slice(0, length);
+}
+function revive({ rows, schema, date, ...meta }) {
+    for (const column of schema) {
+        switch (column.type) {
+            case "bigint": {
+                const { name } = column;
+                for (const row of rows) {
+                    const value = row[name];
+                    if (value == null)
+                        continue;
+                    row[name] = BigInt(value);
+                }
+                break;
+            }
+            case "date": {
+                const { name } = column;
+                for (const row of rows) {
+                    const value = row[name];
+                    if (value == null)
+                        continue;
+                    row[name] = new Date(value);
+                }
+                break;
+            }
+        }
+    }
+    if (date != null)
+        date = new Date(date);
+    return Object.assign(rows, { schema, date }, meta);
+}
+DatabaseClient.hash = hash;
+DatabaseClient.revive = revive;
+DatabaseClient.prototype = DatabaseClientImpl.prototype; // instanceof
+Object.defineProperty(DatabaseClientImpl, "name", { value: "DatabaseClient" }); // prevent mangling

package/dist/src/runtime/stdlib/fileAttachment.d.ts

@@ -3,35 +3,62 @@ export type DsvOptions = {
     array?: boolean;
     typed?: boolean;
 };
-export type DsvResult = any[] & {
+export type DsvResult = (Record<string, any>[] | any[][]) & {
     columns: string[];
 };
 export interface FileAttachment {
+    /** The URL of the file. */
+    href: string;
+    /** The name of the file (not including the path), such as "test.csv". */
     name: string;
+    /** The MIME type, such as "text/csv". */
     mimeType: string;
-    href: string;
-    lastModified: number | undefined;
-    size: number | undefined;
+    /** The time this file was most-recently modified, as milliseconds since epoch, if known. */
+    lastModified?: number;
+    /** The size of this file in bytes, if known. */
+    size?: number;
+    /** @deprecated use FileAttachment.href instead */
     url(): Promise<string>;
+    /** Returns the contents of this file as a Blob. */
     blob(): Promise<Blob>;
+    /** Returns the contents of this file as an ArrayBuffer. */
     arrayBuffer(): Promise<ArrayBuffer>;
+    /** Returns the contents of this file as a string with the given encoding. */
     text(encoding?: string): Promise<string>;
+    /** Returns the contents of this file as JSON. */
     json(): Promise<any>;
+    /** Returns a byte stream to the contents of this file. */
     stream(): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
+    /** Returns the contents of this file as delimiter-separated values. */
     dsv(options?: DsvOptions): Promise<DsvResult>;
-    csv(options?: Exclude<DsvOptions, "delimiter">): Promise<DsvResult>;
-    tsv(options?: Exclude<DsvOptions, "delimiter">): Promise<DsvResult>;
+    /** Returns the contents of this file as comma-separated values. */
+    csv(options?: Omit<DsvOptions, "delimiter">): Promise<DsvResult>;
+    /** Returns the contents of this file as tab-separated values. */
+    tsv(options?: Omit<DsvOptions, "delimiter">): Promise<DsvResult>;
+    /** Returns the contents of this file as an image. */
     image(props?: Partial<HTMLImageElement>): Promise<HTMLImageElement>;
+    /** Returns the contents of this Arrow IPC file as an Apache Arrow table. */
     arrow(): Promise<any>;
+    /** Returns the contents of this file as an Arquero table. */
     arquero(options?: any): Promise<any>;
+    /** Returns the contents of this Parquet file as an Apache Arrow table. */
     parquet(): Promise<any>;
+    /** Returns the contents of this file as an XML document. */
     xml(mimeType?: DOMParserSupportedType): Promise<Document>;
+    /** Returns the contents of this file as an HTML document. */
     html(): Promise<Document>;
 }
-export declare function FileAttachment(name: string, base?: string): FileAttachment;
-export declare namespace FileAttachment {
-    var prototype: FileAttachmentImpl;
+export declare const FileAttachment: {
+    (name: string, base?: string): FileAttachment;
+    prototype: FileAttachmentImpl;
+};
+export interface FileInfo {
+    path: string;
+    mimeType?: string;
+    lastModified?: number;
+    size?: number;
 }
+export declare function registerFile(name: string, info: FileInfo, base?: string | URL): FileAttachmentImpl | undefined;
 export declare abstract class AbstractFile implements FileAttachment {
     name: string;
     mimeType: string;
@@ -50,8 +77,8 @@ export declare abstract class AbstractFile implements FileAttachment {
         array?: boolean | undefined;
         typed?: boolean | undefined;
     }): Promise<DsvResult>;
-    csv(options: Exclude<DsvOptions, "delimiter">): Promise<DsvResult>;
-    tsv(options: Exclude<DsvOptions, "delimiter">): Promise<DsvResult>;
+    csv(options?: Omit<DsvOptions, "delimiter">): Promise<DsvResult>;
+    tsv(options?: Omit<DsvOptions, "delimiter">): Promise<DsvResult>;
     image(props?: Partial<HTMLImageElement>): Promise<HTMLImageElement>;
     arrow(): Promise<any>;
     arquero(options?: any): Promise<any>;