Documentation menu
API referenceMarkdown ↗

maligator:assets

On this page
API reference0.1.0-alpha.35

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.

typescript
export const embedFile: (specifier: string, options?: EmbedFileOptions) => EmbeddedFile;

Types: EmbeddedFile, EmbedFileOptions

typescript
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.

typescript
export const embedDirectory: (specifier: string, options?: EmbedDirectoryOptions) => EmbeddedDirectory;

Types: EmbeddedDirectory, EmbedDirectoryOptions

typescript
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
typescript
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.

typescript
baseDirectory?: string;

EmbeddedFile

A file the build embeds. maligator build fixes its contents; other commands read the source file each time.

Full TypeScript declaration
typescript
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.

typescript
readonly path: string;

EmbeddedFile.size

The size in bytes.

typescript
readonly size: number;

EmbeddedFile.digest

Lowercase hexadecimal SHA-256 of the contents.

typescript
readonly digest: string;

EmbeddedFile.type

The media type implied by the file extension; text types carry charset=utf-8.

typescript
readonly type: string;

EmbeddedFile.bytes

The contents as a Uint8Array over an immutable ArrayBuffer.

typescript
bytes(): Uint8Array<ArrayBuffer>;

EmbeddedFile.text

The contents decoded as UTF-8, without a byte order mark.

typescript
text(): string;

EmbeddedFile.json

The contents parsed as JSON.

typescript
json(): unknown;

EmbeddedFile.materialize

A filesystem path to the contents. Treat it as read-only.

typescript
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
typescript
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.

typescript
files(): ReadonlyArray<EmbeddedFile>;

Types: EmbeddedFile

EmbeddedDirectory.get

The member file at a slash-separated path, if any.

typescript
get(path: string): EmbeddedFile | undefined;

Types: EmbeddedFile

EmbeddedDirectory.materialize

A filesystem path to a directory holding the member files. Treat it as read-only.

typescript
materialize(options?: MaterializeOptions): string;

Types: MaterializeOptions

EmbedProducer

A command that writes the declared files.

Full TypeScript declaration
typescript
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.

typescript
command: ReadonlyArray<string>;

EmbedProducer.cwd

The working directory, resolved from the declaring module. Defaults to its directory.

typescript
cwd?: string;

EmbedWatchProducer

A long-running command that keeps the declared files current, such as a frontend dev server.

Full TypeScript declaration
typescript
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.

typescript
url?: string;

EmbedProducerUse

Which producer each command runs. existing uses the files already on disk; a selected producer must be declared.

Full TypeScript declaration
typescript
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.

typescript
build?: 'build' | 'existing';

EmbedProducerUse.run

Defaults to build.

typescript
run?: 'build' | 'watch' | 'existing';

EmbedProducerUse.test

Defaults to existing.

typescript
test?: 'build' | 'watch' | 'existing';

EmbedProducerUse.dev

Defaults to watch, or build without a watcher.

typescript
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
typescript
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;
};

Types: EmbedProducer, EmbedWatchProducer, EmbedProducerUse

EmbedFileOptions.build

Runs before the files are read: once per run or test, once per dev session, before a build embeds them.

typescript
build?: EmbedProducer;

Types: EmbedProducer

EmbedFileOptions.watch

Runs alongside the command and stops with it.

typescript
watch?: EmbedWatchProducer;

Types: EmbedWatchProducer

EmbedFileOptions.use

typescript
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
typescript
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.

typescript
include?: ReadonlyArray<string>;

EmbedDirectoryOptions.exclude

Patterns of paths to leave out, even when included.

typescript
exclude?: ReadonlyArray<string>;

EmbedDirectoryOptions.dot

Let wildcards match names that start with a dot. Defaults to false.

typescript
dot?: boolean;
Maligator 0.1.0-alpha.35 · Experimental · Source 7a9e60fb1f28
Edit this page · Compatibility

Search guides and API reference.

Browse the API · Troubleshooting