maligator:assets
On this page
Embed files and directory trees into the application. Each call must take a string literal specifier, resolved like an import from the calling module, and literal options. maligator build captures the files of every declaration the program can reach; other commands read the source files live, so edits need no rebuild.
Import from maligator:assets. This API is experimental. Load declarations as described in Use TypeScript.
maligator build captures the declared files when it compiles, so the executable needs no source files at runtime. Other commands read the source files each time a handle is used: an edit is visible on the next read, and a missing file throws then. See Embed files for a walkthrough.
embedFile
Declare a file to embed and return its handle. Repeated declarations of the same file share one handle.
export const embedFile: (specifier: string, options?: EmbedFileOptions) => EmbeddedFile;Types: EmbeddedFile, EmbedFileOptions
import { embedFile } from "maligator:assets";
const certificate = embedFile("./certs/ca.pem");
console.log(certificate.text().length);embedDirectory
Declare a directory tree to embed and return its handle. Repeated declarations with the same options share one handle.
export const embedDirectory: (specifier: string, options?: EmbedDirectoryOptions) => EmbeddedDirectory;import { embedDirectory } from "maligator:assets";
const migrations = embedDirectory("./migrations", { include: ["*.sql"] });
for (const file of migrations.files()) console.log(file.path);MaterializeOptions
Where an embedded copy is written. Outside maligator build the source file is used in place and this option is ignored.
Full TypeScript declaration
type MaterializeOptions = {
/** Parent directory for a materialized copy. Defaults to the OS temporary directory. */
baseDirectory?: string;
};MaterializeOptions.baseDirectory
Parent directory for a materialized copy. Defaults to the OS temporary directory.
baseDirectory?: string;EmbeddedFile
A file the build embeds. maligator build fixes its contents; other commands read the source file each time.
Full TypeScript declaration
interface EmbeddedFile {
/** The path below its directory declaration, or the file name. */
readonly path: string;
/** The size in bytes. */
readonly size: number;
/** Lowercase hexadecimal SHA-256 of the contents. */
readonly digest: string;
/** The media type implied by the file extension; text types carry `charset=utf-8`. */
readonly type: string;
/** The contents as a Uint8Array over an immutable ArrayBuffer. */
bytes(): Uint8Array<ArrayBuffer>;
/** The contents decoded as UTF-8, without a byte order mark. */
text(): string;
/** The contents parsed as JSON. */
json(): unknown;
/** A filesystem path to the contents. Treat it as read-only. */
materialize(options?: MaterializeOptions): string;
}Types: MaterializeOptions
EmbeddedFile.path
The path below its directory declaration, or the file name.
readonly path: string;EmbeddedFile.size
The size in bytes.
readonly size: number;EmbeddedFile.digest
Lowercase hexadecimal SHA-256 of the contents.
readonly digest: string;EmbeddedFile.type
The media type implied by the file extension; text types carry charset=utf-8.
readonly type: string;EmbeddedFile.bytes
The contents as a Uint8Array over an immutable ArrayBuffer.
bytes(): Uint8Array<ArrayBuffer>;EmbeddedFile.text
The contents decoded as UTF-8, without a byte order mark.
text(): string;EmbeddedFile.json
The contents parsed as JSON.
json(): unknown;EmbeddedFile.materialize
A filesystem path to the contents. Treat it as read-only.
materialize(options?: MaterializeOptions): string;Types: MaterializeOptions
EmbeddedDirectory
A directory tree the build embeds. maligator build fixes its member files; other commands list the source directory each time.
Full TypeScript declaration
interface EmbeddedDirectory {
/** The member files in code point order of their paths. */
files(): ReadonlyArray<EmbeddedFile>;
/** The member file at a slash-separated path, if any. */
get(path: string): EmbeddedFile | undefined;
/** A filesystem path to a directory holding the member files. Treat it as read-only. */
materialize(options?: MaterializeOptions): string;
}Types: MaterializeOptions, EmbeddedFile
EmbeddedDirectory.files
The member files in code point order of their paths.
files(): ReadonlyArray<EmbeddedFile>;Types: EmbeddedFile
EmbeddedDirectory.get
The member file at a slash-separated path, if any.
get(path: string): EmbeddedFile | undefined;Types: EmbeddedFile
EmbeddedDirectory.materialize
A filesystem path to a directory holding the member files. Treat it as read-only.
materialize(options?: MaterializeOptions): string;Types: MaterializeOptions
EmbedProducer
A command that writes the declared files.
Full TypeScript declaration
type EmbedProducer = {
/** The executable and its arguments; no shell interprets them. */
command: ReadonlyArray<string>;
/** The working directory, resolved from the declaring module. Defaults to its directory. */
cwd?: string;
};EmbedProducer.command
The executable and its arguments; no shell interprets them.
command: ReadonlyArray<string>;EmbedProducer.cwd
The working directory, resolved from the declaring module. Defaults to its directory.
cwd?: string;EmbedWatchProducer
A long-running command that keeps the declared files current, such as a frontend dev server.
Full TypeScript declaration
type EmbedWatchProducer = EmbedProducer & {
/** A server the watcher starts; the command waits until it answers. */
url?: string;
};Types: EmbedProducer
EmbedWatchProducer.url
A server the watcher starts; the command waits until it answers.
url?: string;EmbedProducerUse
Which producer each command runs. existing uses the files already on disk; a selected producer must be declared.
Full TypeScript declaration
type EmbedProducerUse = {
/** Defaults to build. */
build?: 'build' | 'existing';
/** Defaults to build. */
run?: 'build' | 'watch' | 'existing';
/** Defaults to existing. */
test?: 'build' | 'watch' | 'existing';
/** Defaults to watch, or build without a watcher. */
dev?: 'build' | 'watch' | 'existing';
};EmbedProducerUse.build
Defaults to build.
build?: 'build' | 'existing';EmbedProducerUse.run
Defaults to build.
run?: 'build' | 'watch' | 'existing';EmbedProducerUse.test
Defaults to existing.
test?: 'build' | 'watch' | 'existing';EmbedProducerUse.dev
Defaults to watch, or build without a watcher.
dev?: 'build' | 'watch' | 'existing';EmbedFileOptions
How the declared files are produced. Only the project's own modules may name commands; they never reach a built executable.
Full TypeScript declaration
type EmbedFileOptions = {
/** Runs before the files are read: once per run or test, once per dev session, before a build embeds them. */
build?: EmbedProducer;
/** Runs alongside the command and stops with it. */
watch?: EmbedWatchProducer;
use?: EmbedProducerUse;
};EmbedFileOptions.build
Runs before the files are read: once per run or test, once per dev session, before a build embeds them.
build?: EmbedProducer;Types: EmbedProducer
EmbedFileOptions.watch
Runs alongside the command and stops with it.
watch?: EmbedWatchProducer;Types: EmbedWatchProducer
EmbedFileOptions.use
use?: EmbedProducerUse;Types: EmbedProducerUse
EmbedDirectoryOptions
Which files of the directory belong to the declaration, and how they are produced. Patterns are relative to the directory and use / separators.
Full TypeScript declaration
type EmbedDirectoryOptions = EmbedFileOptions & {
/** Patterns of member paths, with `*`, `?` and whole-segment `**`. Defaults to every file. Each pattern must match a file. */
include?: ReadonlyArray<string>;
/** Patterns of paths to leave out, even when included. */
exclude?: ReadonlyArray<string>;
/** Let wildcards match names that start with a dot. Defaults to false. */
dot?: boolean;
};Types: EmbedFileOptions
EmbedDirectoryOptions.include
Patterns of member paths, with *, ? and whole-segment **. Defaults to every file. Each pattern must match a file.
include?: ReadonlyArray<string>;EmbedDirectoryOptions.exclude
Patterns of paths to leave out, even when included.
exclude?: ReadonlyArray<string>;EmbedDirectoryOptions.dot
Let wildcards match names that start with a dot. Defaults to false.
dot?: boolean;