# maligator:assets

Maligator 0.1.0-alpha.35 · Experimental
Source revision: 7a9e60fb1f282e577871ac66f8715e30c2dfcf37
Canonical: https://maligator.ddv.tools/api/assets

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](/guides/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](/guides/assets) for a walkthrough.

<a id="embedFile"></a>

## 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`](/api/assets#EmbeddedFile), [`EmbedFileOptions`](/api/assets#EmbedFileOptions)



```typescript
import { embedFile } from "maligator:assets";

const certificate = embedFile("./certs/ca.pem");
console.log(certificate.text().length);
```

<a id="embedDirectory"></a>

## 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`](/api/assets#EmbeddedDirectory), [`EmbedDirectoryOptions`](/api/assets#EmbedDirectoryOptions)



```typescript
import { embedDirectory } from "maligator:assets";

const migrations = embedDirectory("./migrations", { include: ["*.sql"] });
for (const file of migrations.files()) console.log(file.path);
```

<a id="MaterializeOptions"></a>

## MaterializeOptions

Where an embedded copy is written. Outside `maligator build` the source file is used in place and this option is ignored.
<details><summary>Full TypeScript declaration</summary>


```typescript
type MaterializeOptions = {
 /** Parent directory for a materialized copy. Defaults to the OS temporary directory. */
 baseDirectory?: string;
};
```

</details>


<a id="MaterializeOptions.baseDirectory"></a>

### MaterializeOptions.baseDirectory

Parent directory for a materialized copy. Defaults to the OS temporary directory.

```typescript
baseDirectory?: string;
```


<a id="EmbeddedFile"></a>

## EmbeddedFile

A file the build embeds. `maligator build` fixes its contents; other commands read the source file each time.
<details><summary>Full TypeScript declaration</summary>


```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`](/api/assets#MaterializeOptions)


</details>


<a id="EmbeddedFile.path"></a>

### EmbeddedFile.path

The path below its directory declaration, or the file name.

```typescript
readonly path: string;
```


<a id="EmbeddedFile.size"></a>

### EmbeddedFile.size

The size in bytes.

```typescript
readonly size: number;
```


<a id="EmbeddedFile.digest"></a>

### EmbeddedFile.digest

Lowercase hexadecimal SHA-256 of the contents.

```typescript
readonly digest: string;
```


<a id="EmbeddedFile.type"></a>

### EmbeddedFile.type

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

```typescript
readonly type: string;
```


<a id="EmbeddedFile.bytes"></a>

### EmbeddedFile.bytes

The contents as a Uint8Array over an immutable ArrayBuffer.

```typescript
bytes(): Uint8Array<ArrayBuffer>;
```


<a id="EmbeddedFile.text"></a>

### EmbeddedFile.text

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

```typescript
text(): string;
```


<a id="EmbeddedFile.json"></a>

### EmbeddedFile.json

The contents parsed as JSON.

```typescript
json(): unknown;
```


<a id="EmbeddedFile.materialize"></a>

### EmbeddedFile.materialize

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

```typescript
materialize(options?: MaterializeOptions): string;
```

Types: [`MaterializeOptions`](/api/assets#MaterializeOptions)



<a id="EmbeddedDirectory"></a>

## EmbeddedDirectory

A directory tree the build embeds. `maligator build` fixes its member files; other commands list the source directory each time.
<details><summary>Full TypeScript declaration</summary>


```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`](/api/assets#MaterializeOptions), [`EmbeddedFile`](/api/assets#EmbeddedFile)


</details>


<a id="EmbeddedDirectory.files"></a>

### EmbeddedDirectory.files

The member files in code point order of their paths.

```typescript
files(): ReadonlyArray<EmbeddedFile>;
```

Types: [`EmbeddedFile`](/api/assets#EmbeddedFile)



<a id="EmbeddedDirectory.get"></a>

### EmbeddedDirectory.get

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

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

Types: [`EmbeddedFile`](/api/assets#EmbeddedFile)



<a id="EmbeddedDirectory.materialize"></a>

### EmbeddedDirectory.materialize

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

```typescript
materialize(options?: MaterializeOptions): string;
```

Types: [`MaterializeOptions`](/api/assets#MaterializeOptions)



<a id="EmbedProducer"></a>

## EmbedProducer

A command that writes the declared files.
<details><summary>Full TypeScript declaration</summary>


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

</details>


<a id="EmbedProducer.command"></a>

### EmbedProducer.command

The executable and its arguments; no shell interprets them.

```typescript
command: ReadonlyArray<string>;
```


<a id="EmbedProducer.cwd"></a>

### EmbedProducer.cwd

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

```typescript
cwd?: string;
```


<a id="EmbedWatchProducer"></a>

## EmbedWatchProducer

A long-running command that keeps the declared files current, such as a frontend dev server.
<details><summary>Full TypeScript declaration</summary>


```typescript
type EmbedWatchProducer = EmbedProducer & {
 /** A server the watcher starts; the command waits until it answers. */
 url?: string;
};
```

Types: [`EmbedProducer`](/api/assets#EmbedProducer)


</details>


<a id="EmbedWatchProducer.url"></a>

### EmbedWatchProducer.url

A server the watcher starts; the command waits until it answers.

```typescript
url?: string;
```


<a id="EmbedProducerUse"></a>

## EmbedProducerUse

Which producer each command runs. `existing` uses the files already on disk; a selected producer must be declared.
<details><summary>Full TypeScript declaration</summary>


```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';
};
```

</details>


<a id="EmbedProducerUse.build"></a>

### EmbedProducerUse.build

Defaults to build.

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


<a id="EmbedProducerUse.run"></a>

### EmbedProducerUse.run

Defaults to build.

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


<a id="EmbedProducerUse.test"></a>

### EmbedProducerUse.test

Defaults to existing.

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


<a id="EmbedProducerUse.dev"></a>

### EmbedProducerUse.dev

Defaults to watch, or build without a watcher.

```typescript
dev?: 'build' | 'watch' | 'existing';
```


<a id="EmbedFileOptions"></a>

## EmbedFileOptions

How the declared files are produced. Only the project's own modules may name commands; they never reach a built executable.
<details><summary>Full TypeScript declaration</summary>


```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`](/api/assets#EmbedProducer), [`EmbedWatchProducer`](/api/assets#EmbedWatchProducer), [`EmbedProducerUse`](/api/assets#EmbedProducerUse)


</details>


<a id="EmbedFileOptions.build"></a>

### 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`](/api/assets#EmbedProducer)



<a id="EmbedFileOptions.watch"></a>

### EmbedFileOptions.watch

Runs alongside the command and stops with it.

```typescript
watch?: EmbedWatchProducer;
```

Types: [`EmbedWatchProducer`](/api/assets#EmbedWatchProducer)



<a id="EmbedFileOptions.use"></a>

### EmbedFileOptions.use



```typescript
use?: EmbedProducerUse;
```

Types: [`EmbedProducerUse`](/api/assets#EmbedProducerUse)



<a id="EmbedDirectoryOptions"></a>

## EmbedDirectoryOptions

Which files of the directory belong to the declaration, and how they are produced. Patterns are relative to the directory and use `/` separators.
<details><summary>Full TypeScript declaration</summary>


```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`](/api/assets#EmbedFileOptions)


</details>


<a id="EmbedDirectoryOptions.include"></a>

### EmbedDirectoryOptions.include

Patterns of member paths, with `*`, `?` and whole-segment `**`. Defaults to every file. Each pattern must match a file.

```typescript
include?: ReadonlyArray<string>;
```


<a id="EmbedDirectoryOptions.exclude"></a>

### EmbedDirectoryOptions.exclude

Patterns of paths to leave out, even when included.

```typescript
exclude?: ReadonlyArray<string>;
```


<a id="EmbedDirectoryOptions.dot"></a>

### EmbedDirectoryOptions.dot

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

```typescript
dot?: boolean;
```

