@bendyline/molen-pack

Molen content packs: build, open and read zip packs of models and documents from any source.

import { /* … */ } from '@bendyline/molen-pack';

Classes

PackChangedError

The server replaced the pack while it was being read (its ETag changed).

Extends

• Error

Constructors

Constructor

new PackChangedError(url): PackChangedError;

Parameters

url

string

Returns

PackChangedError

Overrides

Error.constructor

---

PackEntryNotFoundError

Extends

• Error

Constructors

Constructor

new PackEntryNotFoundError(pack, path): PackEntryNotFoundError;

Parameters

pack

string

path

string

Returns

PackEntryNotFoundError

Overrides

Error.constructor

Properties

pack

readonly pack: string;

path

readonly path: string;

---

PackIntegrityError

Extends

• Error

Constructors

Constructor

new PackIntegrityError(
   pack, 
   path, 
   detail
): PackIntegrityError;

Parameters

pack

string

path

string

detail

string

Returns

PackIntegrityError

Overrides

Error.constructor

Interfaces

AssetProviderLike

The shape of the client's AssetProvider, so this package needs no client dependency.

Methods

load()

load(ref): Promise<ArrayBuffer>;

Parameters

ref

string

Returns

Promise<ArrayBuffer>

loadText()

loadText(ref): Promise<string>;

Parameters

ref

string

Returns

Promise<string>

---

BuiltPack

Properties

bytes

bytes: Uint8Array;

manifest

manifest: PackManifest;

---

OpenPackOptions

Properties

concurrency?

optional concurrency?: number;

Reads in flight at once (default 6).

expect?

optional expect?: object;

Fail to open unless the manifest's contentHash matches.

contentHash

contentHash: string;

fetch?

optional fetch?: (input, init?) => Promise<Response>;

MDN Reference

Parameters

input

RequestInfo | URL

init?

RequestInit

Returns

Promise<Response>

integrity?

optional integrity?: "crc" | "sha256";

'crc' (default) checks each zip member; 'sha256' also checks every file's hash.

label?

optional label?: string;

Name used in errors and progress (default: the URL, or "bytes"/"blob"/"reader").

maxCacheBytes?

optional maxCacheBytes?: number;

Decoded bytes kept for reuse (default 16 MiB).

mode?

optional mode?: "auto" | "whole" | "range";

'auto' (default) picks whole or range reads; 'whole' downloads the file in one request.

retry?

optional retry?: PackRetryOptions;

signal?

optional signal?: AbortSignal;

Aborts opening and every later read.

sizeHint?

optional sizeHint?: number;

Expected size in bytes; with auto, packs up to wholeThreshold are fetched whole.

wholeThreshold?

optional wholeThreshold?: number;

Default 4 MiB.

Methods

onProgress()?

optional onProgress(progress): void;

Parameters

progress

PackProgress

Returns

void

---

Pack

Properties

label

readonly label: string;

manifest

readonly manifest: PackManifest;

Methods

close()

close(): void;

Abort outstanding reads and drop cached bytes.

Returns

void

has()

has(path): boolean;

Parameters

path

string

Returns

boolean

paths()

paths(): string[];

Every file path, sorted.

Returns

string[]

prefetch()

prefetch(paths, options?): Promise<void>;

Start fetching files now so later reads are served from the cache.

Parameters

paths

readonly string[]

options?

ReadOptions

Returns

Promise<void>

readBytes()

readBytes(path, options?): Promise<ArrayBuffer>;

Parameters

path

string

options?

ReadOptions

Returns

Promise<ArrayBuffer>

readJson()

readJson<T>(path, options?): Promise<T>;

Type Parameters

T

T = unknown

Parameters

path

string

options?

ReadOptions

Returns

Promise<T>

readText()

readText(path, options?): Promise<string>;

Parameters

path

string

options?

ReadOptions

Returns

Promise<string>

---

PackAssetProviderOptions

Properties

fallback?

optional fallback?: AssetProviderLike;

Refs no pack provides go here; without it they are an error.

variant?

optional variant?: string;

Prefer this variant (e.g. "ktx2") when the manifest lists one for the asset.

---

PackFile

Properties

bytes

bytes: Uint8Array;

path

path: string;

Pack-relative POSIX path.

---

PackIndex

A directory listing of built packs, for hosts that publish several.

Properties

format

format: "molen/pack-index@1";

packs

packs: Record<string, PackIndexEntry>;

---

PackIndexEntry

Properties

contentHash

contentHash: string;

file

file: string;

Pack file, relative to the index.

size

size: number;

File size in bytes.

version

version: string;

---

PackManifest

The manifest inside a built pack.

Properties

blocks

blocks: Record<string, PackBlock>;

contentHash

contentHash: string;

sha256 over every logical file (path and content), independent of the zip layout.

entries

entries: Record<string, PackEntry>;

format

format: "molen/pack@1";

id

id: string;

ids

ids: Record<string, string>;

Asset id to the entry path of its runtime file.

license?

optional license?: string;

SPDX expression for the pack's content.

notice?

optional notice?: string;

Path of the entry that carries the pack's attribution notice.

provides

provides: Record<string, string[]>;

Role (e.g. types, stylepack, stars) to the entry paths that provide it.

title?

optional title?: string;

version

version: string;

---

PackOptions

Properties

compression?

optional compression?: "auto" | "store";

auto (default) deflates a member when that saves at least 10%. store writes every member uncompressed: the manifest and contents are identical, only the archive is larger, so a pack built for local reading (a test run) skips the deflate that dominates build time.

id

id: string;

ids?

optional ids?: Record<string, string>;

Asset id to file path. Ids declared by molen/asset@1 sidecars are added automatically.

license?

optional license?: string;

notice?

optional notice?: string;

Path of the file carrying the attribution notice.

provides?

optional provides?: Record<string, string | readonly string[]>;

Role (e.g. types, stylepack) to the file or files that provide it.

solid?

optional solid?: boolean;

Group small text files into compressed solid blocks (default true).

title?

optional title?: string;

version

version: string;

---

PackProgress

Properties

bytes

bytes: number;

Bytes read from the source so far.

label

label: string;

The pack's label (URL, file name, ...).

requests

requests: number;

Reads (network requests, for a URL) so far.

---

PackRetryOptions

Properties

attempts?

optional attempts?: number;

Attempts per request, including the first (default 3).

baseDelayMs?

optional baseDelayMs?: number;

Delay before the first retry; doubles each time (default 250 ms).

maxDelayMs?

optional maxDelayMs?: number;

timeoutMs?

optional timeoutMs?: number;

Per-request deadline (default 30 s).

---

PackSet

Properties

packs

readonly packs: readonly Pack[];

Methods

add()

add(pack): void;

Parameters

pack

Pack

Returns

void

assetProvider()

assetProvider(options?): AssetProviderLike;

An asset provider for the client (assets: { provider }).

Parameters

options?

PackAssetProviderOptions

Returns

AssetProviderLike

close()

close(): void;

Returns

void

provided()

provided(role): object[];

The paths every pack lists for a role (e.g. types), earliest pack first.

Parameters

role

string

Returns

object[]

readBytes()

readBytes(ref, options?): Promise<ArrayBuffer>;

Parameters

ref

string

options?

ReadOptions

Returns

Promise<ArrayBuffer>

readJson()

readJson<T>(ref, options?): Promise<T>;

Type Parameters

T

T = unknown

Parameters

ref

string

options?

ReadOptions

Returns

Promise<T>

readText()

readText(ref, options?): Promise<string>;

Parameters

ref

string

options?

ReadOptions

Returns

Promise<string>

resolve()

resolve(ref): 
  | {
  pack: Pack;
  path: string;
}
  | undefined;

Find the pack and path for a ref: pack:<id>/<path>, an asset id from a manifest's ids, or a bare path. Undefined when no pack has it.

Parameters

ref

string

Returns

| { pack: Pack; path: string; } | undefined

---

RangeReader

Random access to a pack's bytes. Supply one for storage Molen does not know about.

Properties

size

readonly size: number;

Total size in bytes.

Methods

read()

read(
   offset, 
   length, 
   signal?
): Promise<Uint8Array<ArrayBufferLike>>;

Parameters

offset

number

length

number

signal?

AbortSignal

Returns

Promise<Uint8Array<ArrayBufferLike>>

---

ReadOptions

Properties

priority?

optional priority?: "high" | "low";

Low-priority reads wait behind high-priority ones (default 'high').

signal?

optional signal?: AbortSignal;

Type Aliases

PackInput

type PackInput = 
  | string
  | URL
  | Blob
  | ArrayBuffer
  | Uint8Array
  | RangeReader;

Where a pack's bytes come from: a URL, a file the user picked, bytes, or your own reader.

Functions

createPack()

function createPack(files, options): Promise<BuiltPack>;

Build a pack: a deterministic zip whose last member is the manifest.

Parameters

files

readonly PackFile[]

options

PackOptions

Returns

Promise<BuiltPack>

---

createPackSet()

function createPackSet(packs?): PackSet;

Parameters

packs?

readonly Pack[]

Returns

PackSet

---

describePack()

function describePack(files, options): Promise<PackManifest>;

Describe files as a pack manifest with no blocks: entries, ids, roles and the content hash. The content hash covers paths and contents only, so a built pack and its unbuilt source directory report the same one.

Parameters

files

readonly PackFile[]

options

PackOptions

Returns

Promise<PackManifest>

---

isTextPath()

function isTextPath(path): boolean;

Parameters

path

string

Returns

boolean

---

mediaTypeOf()

function mediaTypeOf(path): string;

Parameters

path

string

Returns

string

---

openPack()

function openPack(input, options?): Promise<Pack>;

Open a pack. Reads only the manifest and zip directory; files are fetched when read.

Parameters

input

PackInput

options?

OpenPackOptions

Returns

Promise<Pack>

---

packFromFiles()

function packFromFiles(
   files, 
   options, 
   label?
): Promise<Pack>;

A pack over loose files, with the same manifest a built pack of those files would have. For tests, development, and content generated at runtime.

Parameters

files

readonly PackFile[]

options

PackOptions

label?

string

Returns

Promise<Pack>

---

sha256()

function sha256(bytes): Promise<string>;

Parameters

bytes

Uint8Array

Returns

Promise<string>