bare-bundle
Application bundle format for JavaScript
v1.12.0bare-bundle — Application bundle format for JavaScript.
npm i bare-bundleAPI
Bundle
new Bundle(opts?: BundleOptions)
Create an empty Bundle, optionally supplying a custom File class to back stored files.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
opts? | BundleOptions | — | Options; File defaults to MemoryFile. |
addons: string[]
The keys of files in the bundle that are native addons.
assets: string[]
The keys of files in the bundle that are non-JavaScript assets.
Bundle.from(value: string | Buffer | Bundle): Bundle
Coerce value — a serialized bundle string, a Buffer, or an existing Bundle — into a Bundle.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
value | string | Buffer | Bundle | — | The serialized bundle string or buffer to parse, or an existing Bundle. |
Returns Bundle — The parsed Bundle, or value itself if it is already a Bundle.
Throws
INVALID_BUNDLE_HEADER— the serialized header is not valid JSON.
Bundle.isBundle(value: unknown): value is Bundle
Check whether value is a Bundle.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
value | unknown | — | The value to check. |
Returns value is Bundle — true if value is a Bundle instance or exposes the bundle kind symbol, false otherwise.
Bundle.version: number
The bundle format version this implementation produces and expects.
empty(): boolean
Check whether the bundle contains no files.
Returns boolean — true if the bundle contains no files, false otherwise.
exists(key: string): boolean
Check whether a file exists at key.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
key | string | — | The key of the file to look up. |
Returns boolean — true if a file exists at key, false otherwise.
files: Record<string, MemoryFile>
The bundle's files, keyed by path, as MemoryFile instances.
id: string | null
An optional identifier for the bundle, or null if unset.
imports: RecursiveStringObject
The bundle's import map, mapping specifiers to file keys.
keys(): string[]
Return the keys of all files in the bundle.
main: string | null
The key of the bundle's entry file, or null if unset.
mode(key: string): number
Return the file mode (permission bits) of the file at key, or 0 if it doesn't exist.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
key | string | — | The key of the file to look up. |
mount(root: string | URL, opts?: BundleMountOptions): Bundle
Return a copy of the bundle with all file keys and import/resolution specifiers rewritten as absolute URLs resolved against root.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
root | string | URL | — | The base URL (or URL string) to resolve keys and specifiers against. |
opts? | BundleMountOptions | — | Options; conditions maps import-map condition names to per-condition roots. |
Returns Bundle — A new Bundle with rewritten keys; the original bundle is left unchanged.
read(key: string): Buffer
Return the contents of the file at key as a Buffer, or null if it doesn't exist.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
key | string | — | The key of the file to read. |
resolutions: RecursiveStringObject
The bundle's per-file import resolutions map, used to override the default import map for specific files.
root: string | null
The root this bundle was mounted at, or null if it was never mounted. A file may sit outside it, as one unmounted from outside the root does.
toBuffer(opts?: BundleToBufferOptions): Buffer
Serialize the bundle to a single Buffer containing its header and file contents.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
opts? | BundleToBufferOptions | — | Options; indent defaults to 0 and shared to false. |
type(key: string): string | null
Return the module type of the file at key, or null if it is unknown or the file doesn't exist.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
key | string | — | The key of the file to look up. |
unmount(root: string | URL, opts?: BundleMountOptions): Bundle
Return a copy of the bundle with all file keys and import/resolution specifiers rewritten as paths relative to root, reversing mount().
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
root | string | URL | — | The base URL (or URL string) to make keys and specifiers relative to. |
opts? | BundleMountOptions | — | Options; conditions maps import-map condition names to per-condition roots. |
Returns Bundle — A new Bundle with rewritten keys; the original bundle is left unchanged.
version: number
The bundle format version this implementation produces and expects.
write(key: string, data: string, opts?: BundleWriteOptions): this
Add or replace the file at key with data, optionally marking it as the main entry, an addon, an asset, or aliased in the import map.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
key | string | — | The key (path) to store the file under. |
data | string | — | The file contents. |
opts? | BundleWriteOptions | — | Options; main, addon, asset, and executable default to false, and alias and imports to unset. |
Returns this — The bundle itself, for chaining writes.
Throws
TypeError—keyis not a string, oropts.typeis neither a string nornull.
MemoryFile
new MemoryFile(data: string | Buffer, opts?: MemoryFileOptions)
Create a MemoryFile from data, optionally marking it executable or setting an explicit mode.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
data | string | Buffer | — | The file contents; a string is converted to a Buffer. |
opts? | MemoryFileOptions | — | Options; mode defaults to 0o755 when executable is true, otherwise 0o644. |
mode(): number
Return the file's mode (permission bits).
read(): Buffer
Return the file's contents as a Buffer.
size(): number
Return the file's byte length.
type(): string | null
Return the module type the file is loaded as, or null if unknown.
Types
MemoryFileOptions
interface MemoryFileOptions {
executable?: boolean
mode?: number
type?: string | null
}BundleOptions
interface BundleOptions {
File?: typeof MemoryFile
}BundleWriteOptions
interface BundleWriteOptions {
addon?: boolean
alias?: string
asset?: boolean
executable?: boolean
imports?: RecursiveStringObject
main?: boolean
mode?: number
type?: string | null
}BundleMountOptions
interface BundleMountOptions {
conditions?: { [condition: string]: string | URL }
}BundleToBufferOptions
interface BundleToBufferOptions {
indent?: number
shared?: boolean
}Format
[#!hashbang]
<header length><header><...files>The header length is an integer literal denoting the total length of the header. The header itself is a JSON string literal of header length bytes and has the following format:
{
"version": 0,
"id": null | "<string>",
"main": null | "<url>",
"imports": {
"<from>": "<to>"
},
"resolutions": {
"<url>": "<imports>"
},
"addons": ["<url>"],
"assets": ["<url>"],
"files": {
"<url>": {
"offset": number,
"length": number,
"mode": number,
"type"?: "<type>"
}
}
}For each <url> in files, offset provides the byte offset to the file after the header and length provides the byte length of the file.
The optional type records the module type the file is loaded as, using the names of the type import attribute: script, module, json, text, binary, addon, or bundle. When it is left out, the type is inferred when the file is loaded, as for a file outside a bundle.
The bundle may optionally be prefixed with a hashbang, #!, for use with script interpreters. The hashbang is ignored during parsing.
See also
- Bare modules — the full
bare-*catalog. - Bare runtime API — the runtime these modules extend.
Last updated on