Appearance
@bendyline/molen-pack/node
Molen content packs: build, open and read zip packs of models and documents from any source.
ts
import { /* … */ } from '@bendyline/molen-pack/node';Interfaces
BuiltPackFile
Properties
file
ts
file: string;File name, <id>-<first 12 hex of the file's sha256>.zip.
fileSha256
ts
fileSha256: string;sha256 of the file's bytes.
indexPath
ts
indexPath: string;Path of the updated index.json.
manifest
ts
manifest: PackManifest;path
ts
path: string;Absolute path of the written file.
size
ts
size: number;HostedPacks
Properties
index
ts
index: PackIndex;indexPath
ts
indexPath: string;Path of the written index.json.
reused
ts
reused: string[];Pack ids whose version directory was already complete.
written
ts
written: string[];Pack ids written by this call.
zipped
ts
zipped: string[];Pack ids published as their zip rather than unzipped.
HostPacksOptions
Properties
outDir
ts
outDir: string;Where to publish: <pack id>/<version>/… per pack, then index.json.
zipBelow?
ts
optional zipBelow?: number;Publish a pack as its zip when the zip is at most this many bytes (default HOSTED_ZIP_BELOW); larger packs are published unzipped. 0 unzips every pack.
Methods
include()?
ts
optional include(id): boolean;Which pack ids to publish (default: every pack in the index).
Parameters
id
string
Returns
boolean
log()?
ts
optional log(line): void;Parameters
line
string
Returns
void
PackSource
Properties
config
ts
config: PackSourceConfig;dir
ts
dir: string;files
ts
files: PackFile[];Variables
HOSTED_ZIP_BELOW
ts
const HOSTED_ZIP_BELOW: number;The largest zip hostPacks publishes as is (4 MiB): readers fetch an archive this small whole (openPack's wholeThreshold, cachingRangeReader's wholeBelow), so it costs one request however many files it holds.
PACK_INDEX_FILE
ts
const PACK_INDEX_FILE: "index.json" = "index.json";Index written next to built packs.
PACK_SOURCE_FILE
ts
const PACK_SOURCE_FILE: "molen-pack.source.json" = "molen-pack.source.json";Build settings file in a pack's source directory.
Functions
buildPack()
ts
function buildPack(dir, options): Promise<BuiltPackFile>;Build a pack source directory into outDir. The file name carries a hash of its bytes, so a host can cache it forever; index.json in outDir maps the pack id to its current file, and the previous build of the same pack is removed.
Parameters
dir
string
options
compression?
"auto" | "store"
outDir
string
solid?
boolean
Returns
Promise<BuiltPackFile>
extractPack()
ts
function extractPack(pack, outDir): Promise<string[]>;Write every file of a pack into outDir, with a molen-pack.source.json that builds it back to the same content.
Parameters
pack
outDir
string
Returns
Promise<string[]>
hostedVersionDir()
ts
function hostedVersionDir(contentHash): string;A pack version's directory: the first 12 hex digits of its contentHash.
Parameters
contentHash
string
Returns
string
hostPacks()
ts
function hostPacks(sourceIndexPath, options): Promise<HostedPacks>;Publish the packs a pack index lists (a molen/pack-index@1 file beside its built zips) for a CDN. Each pack version goes to <id>/<12 hex of its contentHash>/ once and never changes, so a host can serve those files as immutable. A pack whose zip is at most zipBelow bytes is published as that zip, which readers fetch whole in one request; a larger one is published unzipped, every file at its own path, so readers fetch only the files they use. index.json, written last and the only document that changes between releases, names each version's zip or molen-pack.json. Complete versions from an earlier run are kept; older versions are left in place for clients still holding an older index.
Parameters
sourceIndexPath
string
options
Returns
Promise<HostedPacks>
listPackSource()
ts
function listPackSource(dir): Promise<{
config: PackSourceConfig;
dir: string;
paths: string[];
}>;List validated source settings and included paths without loading file contents.
Parameters
dir
string
Returns
Promise<{ config: PackSourceConfig; dir: string; paths: string[]; }>
openDirPack()
ts
function openDirPack(dir, options?): Promise<Pack>;Open an unbuilt pack source directory as a pack. It has the manifest the built pack would have (same entries, ids and contentHash), without zipping anything.
Parameters
dir
string
options?
Pick<OpenPackOptions, "expect">
Returns
Promise<Pack>
openFilePack()
ts
function openFilePack(path, options?): Promise<Pack>;Open a built pack file. Reads go to the file on demand; close() releases it.
Parameters
path
string
options?
Returns
Promise<Pack>
openPackAt()
ts
function openPackAt(source, options?): Promise<Pack>;Open a pack from a URL, a built pack file, or a pack source directory.
Parameters
source
string
options?
Returns
Promise<Pack>
readPackSource()
ts
function readPackSource(dir): Promise<PackSource>;Read a pack's source directory: its settings file and every file it includes.
Parameters
dir
string
Returns
Promise<PackSource>
recordInPackIndex()
ts
function recordInPackIndex(
outDir,
id,
entry
): Promise<string>;List a pack file in outDir/index.json (a molen/pack-index@1 document), replacing the entry for the same pack id and deleting that entry's previous file when nothing else lists it. Returns the index path. A browser opens packs from that index (openPacksFromIndex in molen-earth).
Parameters
outDir
string
id
string
entry
Returns
Promise<string>
writeDirectoryPack()
ts
function writeDirectoryPack(pack, outDir): Promise<{
manifest: PackManifest;
manifestBytes: number;
}>;Write pack unzipped, for static hosting: every file at its own path under outDir, then a molen-pack.json that lists them loose (no solid blocks) with the same contentHash. Serve the directory and openPack('<url>/molen-pack.json') reads it back. The manifest is written last, so a directory without one is an interrupted write.
Parameters
pack
outDir
string
Returns
Promise<{ manifest: PackManifest; manifestBytes: number; }>