@johnhenry/packfile 0.0.0 → 0.0.1

package/README.md

@@ -197,7 +197,7 @@ Uses SHA-256 hashing (same as file ETags) for consistent cache keys.
 import { fromArchive, toArchive, createRouter } from '@johnhenry/packfile/browser';
 ```
 
-The browser bundle provides `fromArchive`, `toArchive`, and `createRouter`, using the `wbn` package directly (no Node APIs required) and Web Crypto for hashing -- same wire format as the Node entrypoint, so an archive built by one is directly readable by the other.
+The browser bundle provides `fromArchive`, `toArchive`, and `createRouter`, using the `wbn` package directly (no Node APIs required) and Web Crypto for hashing -- same wire format as the Node entrypoint, so an archive built by one is directly readable by the other. **`toArchive()` here returns an `ArrayBuffer`, not the `Buffer` the Node `.` entry's `toArchive()` returns** (or a `Uint8Array` when called with `{ compressed: false }`) -- there is no `Buffer` in a browser. Types for this subpath are declared in `browser.d.ts` (see `./browser`'s `types` condition in `package.json`).
 
 ```js
 const archive = await fetch('/app.wbn').then(r => r.arrayBuffer());
@@ -405,6 +405,15 @@ import { compressObject, deCompressObject } from '@johnhenry/packfile/compressio
 | `./blob-preview` | `lib/blob-preview.mjs` | `createBlobPreview` — host a `FilesMap` client-side via `blob:` URLs, no server |
 | `./web-bundle` | `lib/web-bundle.mjs` | Lower-level Web Bundle primitives: `toWebBundle`, `fromWebBundle`, `createWebBundleRouter` — the engine `toArchive`/`fromArchive` are built on, with a real `baseURL`/headers/IWA-signing exposed |
 
+TypeScript types: `.`, `./browser`, and `./blob-preview` each have a `types`
+condition and a real `.d.ts` file (`types.d.ts`, `browser.d.ts`,
+`blob-preview.d.ts`). The remaining subpaths (`./compat`, `./cache`,
+`./hash`, `./compression`, `./web-bundle`) do not yet -- importing from one
+of those in TypeScript will type-check as `any`, not a compile error, but
+also not real type safety. (`./browser` and `./blob-preview` were fixed in
+[#5](https://github.com/johnhenry/packfile/issues/5); the others are open,
+unfixed instances of the same gap.)
+
 ## Security model
 
 **What packfile guarantees:**

package/blob-preview.d.ts

@@ -0,0 +1,86 @@
+import { FilesMap } from "./types";
+
+export { FilesMap };
+
+// Note: `blob-preview.d.ts` describes the `./blob-preview` entry point
+// (`lib/blob-preview.mjs`), whose only export is `createBlobPreview`.
+
+/** Why a reference was left unrewritten (see README "What this does and
+ * does not solve"): either the target path doesn't exist in the given
+ * `FilesMap` ("missing"), or resolving it would require a file that's
+ * still mid-finalization -- a genuine reference cycle ("cycle"). */
+export type UnresolvedReferenceReason = "missing" | "cycle";
+
+export type UnresolvedReferenceInfo = {
+  reason: UnresolvedReferenceReason;
+  targetPath: string;
+  fromPath: string;
+};
+
+export type CreateBlobPreviewOptions = {
+  /** The entry-point path, must exist in `files`. Default `"index.html"`. */
+  rootPath?: string;
+  /** Throw instead of warning when a relative reference can't be resolved
+   * (missing file, or a reference-cycle closing edge). Default `false`. */
+  strict?: boolean;
+  /** Called instead of the default `console.warn` for every reference this
+   * module leaves unrewritten because it couldn't (or, for cycles,
+   * shouldn't) be resolved. Ignored when `strict` is set (which throws
+   * instead). */
+  onUnresolvedReference?: (info: UnresolvedReferenceInfo) => void;
+};
+
+/**
+ * A registry of in-memory JS files, each backed by its own `blob:` URL.
+ *
+ * This is a duplicate of `@johnhenry/andbox`'s own `VirtualModuleRegistry`
+ * interface (from `createVirtualModuleRegistry()`, which `createBlobPreview`
+ * uses internally for JS specifier resolution), not an import of it: as of
+ * this writing `@johnhenry/andbox`'s `package.json` has no `types`
+ * condition of its own (the same class of bug this file's sibling
+ * `browser.d.ts` fixes for this package -- see packfile issue #5), so
+ * `import("@johnhenry/andbox").VirtualModuleRegistry` does not resolve for
+ * a consumer of *this* package under `moduleResolution: "nodenext"`/
+ * `"bundler"`. Duplicated here deliberately so this package's own types
+ * stay resolvable regardless of that separate, upstream issue; keep this
+ * in sync with `@johnhenry/andbox`'s `src/index.d.ts` if it changes.
+ */
+export interface VirtualModuleRegistry {
+  /** Get the `blob:` URL registered for a path, or `null` if unknown. */
+  resolve(path: string): string | null;
+  /** Resolve a module specifier the way `import` would, from the point of
+   * view of a given importing file: import-map resolution first, then a
+   * relative-path fallback, then `null` if neither matched. */
+  resolveSpecifier(specifier: string, parentPath?: string): string | null;
+  /** Register (or replace) a file at runtime. Returns the new blob URL. */
+  define(path: string, source: string): string;
+  /** Whether a path is registered. */
+  has(path: string): boolean;
+  /** All registered paths. */
+  paths(): string[];
+  /** Revoke every blob URL this registry has ever minted. */
+  dispose(): void;
+  /** Whether `dispose()` has been called. */
+  isDisposed(): boolean;
+}
+
+export type BlobPreview = {
+  /** `blob:` URL for `rootPath`. */
+  entryUrl: string;
+  /** Look up the `blob:` URL minted for a given packaged path. */
+  resolve(path: string): string | null;
+  /** Revokes every `blob:` URL this call minted. */
+  dispose(): void;
+  /** The underlying andbox registry, for advanced JS-specifier resolution. */
+  registry: VirtualModuleRegistry;
+};
+
+/**
+ * Turn a packfile `FilesMap` into a set of `blob:` URLs suitable for hosting
+ * inside a browser tab/iframe with no server. For trusted/your-own content
+ * only -- see README's "What this does and does not solve".
+ */
+export function createBlobPreview(
+  files: FilesMap,
+  options?: CreateBlobPreviewOptions
+): Promise<BlobPreview>;

package/browser.d.ts

@@ -0,0 +1,86 @@
+import { FileEntry, FilesMap, RouterOptions, RouteHandler } from "./types";
+
+export { FileEntry, FilesMap, RouterOptions, RouteHandler };
+
+// Note: `browser.d.ts` describes the `./browser` entry point (`browser.mjs`),
+// not the main `.` entry (see `types.d.ts` for that). `createRouter` is the
+// exact same implementation as the `.` entry's (both import
+// `./lib/create-router.mjs`), so its types are reused unchanged. `toArchive`
+// and `fromArchive`, however, are a *separate* implementation from the Node
+// entry's (`lib/to-archive.mjs`/`lib/from-archive.mjs`) -- same wire format,
+// but different runtime types, because there is no `Buffer` in a browser:
+//
+// - `toArchive()`'s options key is `compressed` here, not `compress` (the
+//   Node entry's key) -- a real, pre-existing naming inconsistency between
+//   the two entrypoints, not a typo introduced by this file. There is also
+//   no `compressionLevel` option here (browser.mjs's own comment notes
+//   `CompressionStream` has no level parameter to plumb one through to).
+// - `toArchive()` returns a `Uint8Array` when called with
+//   `{ compressed: false }` (the raw, uncompressed Web Bundle from
+//   `wbn`'s `BundleBuilder.createBundle()`), and an `ArrayBuffer` when
+//   compression runs (the default): `compressObject()`
+//   (`lib/compression.browser.mjs`) pipes through `CompressionStream` and
+//   resolves via `Response#arrayBuffer()`. The Node entry's `toArchive()`,
+//   by contrast, always returns a `Buffer`. Don't assume this matches the
+//   Node types -- confirmed by reading both implementations, not guessed.
+// - `fromArchive()`'s `buffer` parameter is `ArrayBuffer | Uint8Array`, not
+//   `Buffer | ArrayBuffer | Uint8Array` like the Node entry -- there is no
+//   `Buffer` global to accept in a browser build.
+
+export type BrowserToArchiveOptions = {
+  /** Default `true`. When `false`, skips compression and returns the raw
+   * Web Bundle bytes as a `Uint8Array` instead of an `ArrayBuffer`. */
+  compressed?: boolean;
+};
+
+export type BrowserFromArchiveOptions = {
+  /** Default `true`. Set `false` if `buffer` is an uncompressed Web Bundle. */
+  compressed?: boolean;
+};
+
+/**
+ * Serializes a file Map to a (by default gzip-compressed) Web Bundle.
+ * Returns an `ArrayBuffer` when compressed (the default); returns the raw
+ * `Uint8Array` bundle directly when called with `{ compressed: false }`.
+ * Same wire format as the Node `.` entry's `toArchive()`, which always
+ * returns a `Buffer` -- the two are readable by each other regardless.
+ *
+ * Declared as overloads (rather than a single `Promise<ArrayBuffer |
+ * Uint8Array>` signature) so a literal `{ compressed: false }` narrows the
+ * return type precisely instead of forcing every caller to deal with the
+ * union.
+ */
+export function toArchive(
+  map: Map<string, FileEntry>,
+  options?: { compressed?: true }
+): Promise<ArrayBuffer>;
+export function toArchive(
+  map: Map<string, FileEntry>,
+  options: { compressed: false }
+): Promise<Uint8Array>;
+export function toArchive(
+  map: Map<string, FileEntry>,
+  options?: BrowserToArchiveOptions
+): Promise<ArrayBuffer | Uint8Array>;
+
+/**
+ * Deserializes a (by default gzip-compressed) Web Bundle back into a
+ * `Map<string, FileEntry>`. Accepts an `ArrayBuffer` or `Uint8Array` --
+ * there is no `Buffer` global in a browser build.
+ */
+export function fromArchive(
+  buffer: ArrayBuffer | Uint8Array,
+  options?: BrowserFromArchiveOptions
+): Promise<Map<string, FileEntry>>;
+
+/**
+ * Returns a `(input, ctx?) => Promise<Response>` handler that serves files
+ * from a `Map`/`LazyFileMap`. `input` may be a path string or a `Request`.
+ * The returned function also has itself assigned to `.fetch`. Identical
+ * implementation to the `.` entry's `createRouter` (both import
+ * `./lib/create-router.mjs`).
+ */
+export function createRouter(
+  files: FilesMap,
+  options?: RouterOptions
+): RouteHandler;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/packfile",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "type": "module",
   "main": "index.mjs",
   "types": "./types.d.ts",
@@ -24,6 +24,7 @@
   },
   "scripts": {
     "test": "node --test test.mjs",
+    "typecheck": "tsc --project test/types-fixture/tsconfig.json",
     "demo:compile": "node demo/compile.mjs",
     "demo:server": "node demo/server.mjs",
     "demo:browser": "npx serve ."
@@ -38,6 +39,7 @@
   },
   "devDependencies": {
     "theres-waldo": "^0.0.0",
+    "typescript": "^7.0.2",
     "wbn-sign": "^0.3.1"
   },
   "exports": {
@@ -45,21 +47,29 @@
       "types": "./types.d.ts",
       "default": "./index.mjs"
     },
-    "./browser": "./browser.mjs",
+    "./browser": {
+      "types": "./browser.d.ts",
+      "default": "./browser.mjs"
+    },
     "./compat": "./compat.mjs",
     "./cache": "./cache.mjs",
     "./hash": "./lib/hash.mjs",
     "./compression": "./lib/compression.mjs",
-    "./blob-preview": "./lib/blob-preview.mjs",
+    "./blob-preview": {
+      "types": "./blob-preview.d.ts",
+      "default": "./lib/blob-preview.mjs"
+    },
     "./web-bundle": "./lib/web-bundle.mjs"
   },
   "files": [
     "index.mjs",
     "browser.mjs",
+    "browser.d.ts",
     "compat.mjs",
     "cache.mjs",
     "packfile.mjs",
     "lib/",
+    "blob-preview.d.ts",
     "types.d.ts",
     "types.ts",
     "README.md",