@observablehq/notebook-kit 1.1.0-rc.7 → 1.1.0-rc.9

package/dist/package.json

@@ -5,7 +5,7 @@
         "type": "git",
         "url": "git+https://github.com/observablehq/notebook-kit.git"
     },
-    "version": "1.1.0-rc.7",
+    "version": "1.1.0-rc.9",
     "type": "module",
     "scripts": {
         "test": "vitest",
@@ -13,7 +13,7 @@
         "lint": "tsc --noEmit && eslint bin src types",
         "notebooks": "tsx bin/notebooks.ts",
         "download": "tsx bin/notebooks.ts download",
-        "docs:preview": "tsx --watch bin/notebooks.ts preview --root docs --template docs/observable.tmpl",
+        "docs:preview": "tsx --watch bin/notebooks.ts preview --base /notebook-kit/ --root docs --template docs/observable.tmpl",
         "docs:build": "tsx bin/notebooks.ts build --root docs --template docs/observable.tmpl -- $(find docs -path 'docs/.observable' -prune -o -name '*.html' -print)"
     },
     "bin": {

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

@@ -1,4 +1,5 @@
 import type { ColumnSchema, QueryParam } from "../runtime/index.js";
+export { hash as getQueryHash, nameHash as getNameHash } from "../lib/hash.js";
 export type DatabaseConfig = DuckDBConfig | SnowflakeConfig | PostgresConfig;
 export type DuckDBConfig = {
     type: "duckdb";
@@ -29,12 +30,13 @@ export type PostgresConfig = {
 export type DatabaseContext = {
     cwd: string;
 };
-export type QueryTemplateFunction = (strings: string[], ...params: QueryParam[]) => Promise<SerializableQueryResult>;
+export type QueryTemplateFunction = (strings: readonly string[], ...params: QueryParam[]) => Promise<SerializableQueryResult>;
 export type SerializableQueryResult = {
     rows: Record<string, unknown>[];
     schema: ColumnSchema[];
     duration: number;
     date: Date;
 };
+export declare function getDatabaseConfig(sourcePath: string, databaseName: string): Promise<DatabaseConfig>;
 export declare function getDatabase(config: DatabaseConfig, context: DatabaseContext): Promise<QueryTemplateFunction>;
-export declare function isDefaultDatabase(name: string): name is "postgres" | "duckdb";
+export declare function getQueryCachePath(sourcePath: string, databaseName: string, strings: readonly string[], ...params: unknown[]): Promise<string>;

package/dist/src/databases/index.js

@@ -1,3 +1,34 @@
+import { createReadStream } from "node:fs";
+import { dirname, join } from "node:path";
+import { json } from "node:stream/consumers";
+import { isEnoent } from "../lib/error.js";
+import { hash as getQueryHash, nameHash as getNameHash } from "../lib/hash.js";
+export { hash as getQueryHash, nameHash as getNameHash } from "../lib/hash.js";
+export async function getDatabaseConfig(sourcePath, databaseName) {
+    const sourceDir = dirname(sourcePath);
+    const configPath = join(sourceDir, ".observable", "databases.json");
+    let config;
+    try {
+        const configStream = createReadStream(configPath, "utf-8");
+        const configs = (await json(configStream));
+        config = configs[databaseName];
+    }
+    catch (error) {
+        if (!isEnoent(error))
+            throw error;
+    }
+    if (config === undefined) {
+        if (databaseName === "postgres")
+            config = { type: "postgres" };
+        else if (databaseName === "duckdb")
+            config = { type: "duckdb" };
+        else if (/\.(duck)?db$/i.test(databaseName))
+            config = { type: "duckdb", path: databaseName };
+        else
+            throw new Error(`database not found: ${databaseName}`);
+    }
+    return config;
+}
 export async function getDatabase(config, context) {
     switch (config.type) {
         case "duckdb":
@@ -10,6 +41,8 @@ export async function getDatabase(config, context) {
             throw new Error(`unsupported database type: ${config["type"]}`);
     }
 }
-export function isDefaultDatabase(name) {
-    return name === "postgres" || name === "duckdb";
+export async function getQueryCachePath(sourcePath, databaseName, strings, ...params) {
+    const sourceDir = dirname(sourcePath);
+    const cacheName = `${await getNameHash(databaseName)}-${await getQueryHash(strings, ...params)}.json`;
+    return join(sourceDir, ".observable", "cache", cacheName);
 }

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

@@ -0,0 +1,2 @@
+export declare function hash(strings: readonly string[], ...params: unknown[]): Promise<string>;
+export declare function nameHash(name: string): Promise<string>;

package/dist/src/lib/hash.js

@@ -0,0 +1,20 @@
+import { sluggify } from "./sluggify.js";
+async function sha256(input) {
+    const encoded = new TextEncoder().encode(input);
+    const buffer = await crypto.subtle.digest("SHA-256", encoded);
+    return new Uint8Array(buffer).reduce((i, byte) => (i << 8n) | BigInt(byte), 0n);
+}
+function base36(int, length) {
+    return int.toString(36).padStart(length, "0").slice(0, length);
+}
+export async function hash(strings, ...params) {
+    return base36(await sha256(JSON.stringify([strings, ...params])), 16);
+}
+export async function nameHash(name) {
+    return /^[\w-]+$/.test(name)
+        ? name
+        : `${sluggify(basename(name))}.${base36(await sha256(name), 8)}`;
+}
+function basename(name) {
+    return name.replace(/^.*\//, "");
+}

package/dist/src/lib/hash.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,28 @@
+import { assert, describe, test } from "vitest";
+import { hash, nameHash } from "./hash.js";
+describe("nameHash", () => {
+    test("returns a simple name as-is", async () => {
+        assert.strictEqual(await nameHash("foo"), "foo");
+        assert.strictEqual(await nameHash("foo-bar"), "foo-bar");
+        assert.strictEqual(await nameHash("foo-"), "foo-");
+        assert.strictEqual(await nameHash("-foo"), "-foo");
+    });
+    test("sluggifies and hashes names with special characters", async () => {
+        assert.strictEqual(await nameHash("foo.db"), "foo-db.2s9flvsm");
+        assert.strictEqual(await nameHash("./foo.db"), "foo-db.3ee6cmxd");
+        assert.strictEqual(await nameHash("data/foo.db"), "foo-db.61nrbwb0");
+        assert.strictEqual(await nameHash("bar/foo.db"), "foo-db.1jlqjad7");
+        assert.strictEqual(await nameHash("foo bar"), "foo-bar.69w36b7f");
+    });
+});
+describe("hash", () => {
+    test("returns the expected static hash", async () => {
+        assert.strictEqual(await hash `foo`, "1n7k0l3ilxvth9al");
+        assert.strictEqual(await hash `bar`, "39v7mmkf7sfehxh1");
+        assert.strictEqual(await hash ``, "gepym5nmvuej8503");
+    });
+    test("returns the expected dynamic hash", async () => {
+        assert.strictEqual(await hash `SELECT 1 + ${2}`, "64iqby4orqj5tgek");
+        assert.strictEqual(await hash `SELECT 1 + ${3}`, "1azi8mazfb39kln7");
+    });
+});

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

@@ -0,0 +1,6 @@
+export interface SluggifyOptions {
+    length?: number;
+    fallback?: string;
+    separator?: string;
+}
+export declare function sluggify(string: string, { length, fallback, separator }?: SluggifyOptions): string;

package/dist/src/lib/sluggify.js

@@ -0,0 +1,22 @@
+export function sluggify(string, { length = 50, fallback = "untitled", separator = "-" } = {}) {
+    const parts = string
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f'‘’]/g, "")
+        .toLowerCase()
+        .split(/\W+/g)
+        .filter(nonempty);
+    let i = -1;
+    for (let l = 0, n = parts.length; ++i < n;) {
+        if ((l += parts[i].length) + i > length) {
+            parts[i] = parts[i].substring(0, length - l + parts[i].length - i);
+            break;
+        }
+    }
+    return (parts
+        .slice(0, i + 1)
+        .filter(Boolean)
+        .join(separator) || fallback.slice(0, length));
+}
+function nonempty(string) {
+    return string.length > 0;
+}

package/dist/src/lib/sluggify.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,51 @@
+import { assert, test } from "vitest";
+import { sluggify } from "./sluggify.js";
+test("returns the default fallback for empty slugs", () => {
+    assert.strictEqual(sluggify(""), "untitled");
+    assert.strictEqual(sluggify("  "), "untitled");
+    assert.strictEqual(sluggify("---"), "untitled");
+    assert.strictEqual(sluggify("##)!@#(*"), "untitled");
+});
+test("returns the given fallback for empty slugs", () => {
+    assert.strictEqual(sluggify("", { fallback: "foo" }), "foo");
+    assert.strictEqual(sluggify("  ", { fallback: "foo" }), "foo");
+    assert.strictEqual(sluggify("---", { fallback: "foo" }), "foo");
+    assert.strictEqual(sluggify("##)!@#(*", { fallback: "foo" }), "foo");
+});
+test("lowercases", () => {
+    assert.strictEqual(sluggify("HELLO WORLD"), "hello-world");
+    assert.strictEqual(sluggify("HelLo WorlD"), "hello-world");
+});
+test("removes emoji", () => {
+    assert.strictEqual(sluggify("HELLO 😎"), "hello");
+    assert.strictEqual(sluggify("HELLO 😎 world"), "hello-world");
+    assert.strictEqual(sluggify("HELLO 💩 world"), "hello-world");
+});
+test("trims leading and trailing spaces", () => {
+    assert.strictEqual(sluggify("  hello world   "), "hello-world");
+});
+test("collapses contiguous spaces", () => {
+    assert.strictEqual(sluggify("  hello    world   "), "hello-world");
+});
+test("removes punctuation", () => {
+    assert.strictEqual(sluggify("Hello, world!"), "hello-world");
+    assert.strictEqual(sluggify("Hello, 'world'!"), "hello-world");
+    assert.strictEqual(sluggify('Hello, "world"!'), "hello-world");
+    assert.strictEqual(sluggify("Hello, “world”!"), "hello-world");
+    assert.strictEqual(sluggify("Hello, ‘world’!"), "hello-world");
+    assert.strictEqual(sluggify("Hello, fo'c's'le!"), "hello-focsle");
+    assert.strictEqual(sluggify("Hello, fo’c’s’le!"), "hello-focsle");
+});
+test("removes diacritics and combiners", () => {
+    assert.strictEqual(sluggify("Héllö, wørld!"), "hello-w-rld");
+    assert.strictEqual(sluggify("z̷̢̡̟͍̺͛͆͐̀ą̸̻̰̪͈͒͝ͅl̸͇̘̓g̶̡͈͒̾̉̽̑̅ö̸̧̟́͆"), "zalgo");
+});
+test("allows up to 50 characters after stripping", () => {
+    assert.strictEqual(sluggify("‘A‘ohe pu‘u ki‘eki‘e ke ho ‘ā‘o ‘ia e pi‘i"), "aohe-puu-kiekie-ke-ho-ao-ia-e-pii");
+    assert.strictEqual(sluggify("0123456789012345678901234567890123456789012345678"), "0123456789012345678901234567890123456789012345678");
+    assert.strictEqual(sluggify("01234567890123456789012345678901234567890123456789"), "01234567890123456789012345678901234567890123456789");
+    assert.strictEqual(sluggify("012345678901234567890123456789012345678901234567890"), "01234567890123456789012345678901234567890123456789");
+    assert.strictEqual(sluggify("01234567890 1234567890 1234567890 1234567890 12345678"), "01234567890-1234567890-1234567890-1234567890-12345");
+    assert.strictEqual(sluggify("01234567890 1234567890 1234567890 1234567890 123456789"), "01234567890-1234567890-1234567890-1234567890-12345");
+    assert.strictEqual(sluggify("01234567890 1234567890 1234567890 1234567890 1234567890"), "01234567890-1234567890-1234567890-1234567890-12345");
+});

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

@@ -58,12 +58,12 @@ export declare class NotebookRuntime {
         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>;
+                sql(strings: readonly string[], ...params: import("./stdlib/databaseClient.js").QueryParam[]): Promise<import("./stdlib/databaseClient.js").QueryResult>;
+                cachePath(strings: readonly string[], ...params: import("./stdlib/databaseClient.js").QueryParam[]): Promise<string>;
             };
         };
         FileAttachment: () => {

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

@@ -27,11 +27,10 @@ export interface QueryOptions extends QueryOptionsSpec {
 export interface DatabaseClient {
     readonly name: string;
     readonly options: QueryOptions;
-    sql(strings: string[], ...params: QueryParam[]): Promise<QueryResult>;
+    sql(strings: readonly string[], ...params: QueryParam[]): Promise<QueryResult>;
 }
 export declare const DatabaseClient: {
     (name: string, options?: QueryOptionsSpec): DatabaseClient;
-    hash: typeof hash;
     revive: typeof revive;
     prototype: DatabaseClientImpl;
 };
@@ -39,8 +38,8 @@ declare class DatabaseClientImpl implements DatabaseClient {
     readonly name: string;
     readonly options: QueryOptions;
     constructor(name: string, options: QueryOptions);
-    sql(strings: string[], ...params: QueryParam[]): Promise<QueryResult>;
+    sql(strings: readonly string[], ...params: QueryParam[]): Promise<QueryResult>;
+    cachePath(strings: readonly string[], ...params: QueryParam[]): Promise<string>;
 }
-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

@@ -1,6 +1,5 @@
+import { hash, nameHash } from "../../lib/hash.js";
 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 } = {}) {
@@ -31,19 +30,15 @@ class DatabaseClientImpl {
         });
     }
     async sql(strings, ...params) {
-        const path = `.observable/cache/${this.name}-${await hash(strings, ...params)}.json`;
+        const path = await this.cachePath(strings, ...params);
         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);
+    async cachePath(strings, ...params) {
+        return `.observable/cache/${await nameHash(this.name)}-${await hash(strings, ...params)}.json`;
+    }
 }
 function revive({ rows, schema, date, ...meta }) {
     for (const column of schema) {
@@ -77,7 +72,6 @@ function revive({ rows, schema, date, ...meta }) {
 function asDate(value) {
     return new Date(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}(?::\d{2})?$/.test(value) ? value + "Z" : value);
 }
-DatabaseClient.hash = hash;
 DatabaseClient.revive = revive;
 DatabaseClient.prototype = DatabaseClientImpl.prototype; // instanceof
 Object.defineProperty(DatabaseClientImpl, "name", { value: "DatabaseClient" }); // prevent mangling

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

@@ -48,12 +48,12 @@ export declare const library: {
     width: () => AsyncGenerator<number, void, unknown>;
     DatabaseClient: () => {
         (name: string, options?: import("./databaseClient.js").QueryOptionsSpec): DatabaseClient;
-        hash: (strings: string[], ...params: unknown[]) => Promise<string>;
         revive: ({ rows, schema, date, ...meta }: import("../../databases/index.js").SerializableQueryResult) => import("./databaseClient.js").QueryResult;
         prototype: {
             readonly name: string;
             readonly options: import("./databaseClient.js").QueryOptions;
-            sql(strings: string[], ...params: import("./databaseClient.js").QueryParam[]): Promise<import("./databaseClient.js").QueryResult>;
+            sql(strings: readonly string[], ...params: import("./databaseClient.js").QueryParam[]): Promise<import("./databaseClient.js").QueryResult>;
+            cachePath(strings: readonly string[], ...params: import("./databaseClient.js").QueryParam[]): Promise<string>;
         };
     };
     FileAttachment: () => {

package/dist/src/vite/observable.js

@@ -1,17 +1,15 @@
-import { createReadStream, existsSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { json } from "node:stream/consumers";
 import { dirname, join, resolve } from "node:path";
+import { relative } from "node:path/posix";
 import { fileURLToPath } from "node:url";
 import { JSDOM } from "jsdom";
-import { getDatabase, isDefaultDatabase } from "../databases/index.js";
-import { isEnoent } from "../lib/error.js";
+import { getDatabase, getDatabaseConfig, getQueryCachePath } from "../databases/index.js";
 import { deserialize } from "../lib/serialize.js";
 import { Sourcemap } from "../javascript/sourcemap.js";
 import { transpile } from "../javascript/transpile.js";
 import { parseTemplate } from "../javascript/template.js";
 import { collectAssets } from "../runtime/stdlib/assets.js";
-import { DatabaseClient } from "../runtime/stdlib/databaseClient.js";
 import { highlight } from "../runtime/stdlib/highlight.js";
 import { MarkdownRenderer } from "../runtime/stdlib/md.js";
 export function observable({ window = new JSDOM().window, parser = new window.DOMParser(), template = fileURLToPath(import.meta.resolve("../templates/default.html")), transformTemplate = (template) => template, transformNotebook = (notebook) => notebook } = {}) {
@@ -69,30 +67,13 @@ export function observable({ window = new JSDOM().window, parser = new window.DO
                         const template = parseTemplate(value);
                         if (!template.expressions.length) {
                             const dir = dirname(context.filename);
-                            const cacheDir = join(dir, ".observable", "cache");
-                            const hash = await DatabaseClient.hash.call(null, [value]);
-                            const cacheName = `${cell.database}-${hash}.json`;
-                            const cachePath = join(cacheDir, cacheName);
+                            const cachePath = await getQueryCachePath(context.filename, cell.database, [value]);
                             if (!existsSync(cachePath)) {
-                                let config;
-                                try {
-                                    const configPath = join(dir, ".observable", "databases.json");
-                                    const configStream = createReadStream(configPath, "utf-8");
-                                    const configs = (await json(configStream));
-                                    config = configs[cell.database];
-                                }
-                                catch (error) {
-                                    if (!isEnoent(error))
-                                        throw error;
-                                }
-                                if (isDefaultDatabase(cell.database))
-                                    config ?? (config = { type: cell.database });
-                                if (!config)
-                                    throw new Error(`database not found: ${cell.database}`);
+                                const config = await getDatabaseConfig(context.filename, cell.database);
                                 try {
                                     const database = await getDatabase(config, { cwd: dir });
                                     const results = await database.call(null, [value]);
-                                    await mkdir(cacheDir, { recursive: true });
+                                    await mkdir(dirname(cachePath), { recursive: true });
                                     await writeFile(cachePath, JSON.stringify(results));
                                 }
                                 catch (error) {
@@ -100,7 +81,7 @@ export function observable({ window = new JSDOM().window, parser = new window.DO
                                 }
                             }
                             cell.mode = "js";
-                            cell.value = `FileAttachment(${JSON.stringify(`.observable/cache/${cacheName}`)}).json().then(DatabaseClient.revive)${hidden ? "" : `.then(Inputs.table)${cell.output ? ".then(view)" : ""}`}`;
+                            cell.value = `FileAttachment(${JSON.stringify(relative(dir, cachePath))}).json().then(DatabaseClient.revive)${hidden ? "" : `.then(Inputs.table)${cell.output ? ".then(view)" : ""}`}`;
                         }
                     }
                     collectAssets(assets, div);

package/package.json

@@ -5,7 +5,7 @@
     "type": "git",
     "url": "git+https://github.com/observablehq/notebook-kit.git"
   },
-  "version": "1.1.0-rc.7",
+  "version": "1.1.0-rc.9",
   "type": "module",
   "scripts": {
     "test": "vitest",
@@ -13,7 +13,7 @@
     "lint": "tsc --noEmit && eslint bin src types",
     "notebooks": "tsx bin/notebooks.ts",
     "download": "tsx bin/notebooks.ts download",
-    "docs:preview": "tsx --watch bin/notebooks.ts preview --root docs --template docs/observable.tmpl",
+    "docs:preview": "tsx --watch bin/notebooks.ts preview --base /notebook-kit/ --root docs --template docs/observable.tmpl",
     "docs:build": "tsx bin/notebooks.ts build --root docs --template docs/observable.tmpl -- $(find docs -path 'docs/.observable' -prune -o -name '*.html' -print)"
   },
   "bin": {