Immaculata.dev

Web build tool for serious engineers.

npm i immaculata

Rather than brute forcing solutions, Immaculata provides carefully thought out functions and classes with orthogonal behavior, aiming to reach the perfect blend of convenience and flexibility.

In memory file tree

At the core is LiveTree, which loads a given directory into memory.

import * as import immaculataimmaculata from 'immaculata'

const const tree: immaculata.LiveTreetree = new import immaculataimmaculata.constructor LiveTree(root: string, importMetaUrl: string): immaculata.LiveTreeLiveTree('site', import.meta.ImportMeta.url: string
The absolute `file:` URL of the module.
url)

var console: Console
The `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.

The module exports two specific components:

* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module.

_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for
more information.

Example using the global `console`:

```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```

Example using the `Console` class:

```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```
@see[source](https://github.com/nodejs/node/blob/v22.x/lib/console.js)
console.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)
Prints to `stdout` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)).

```js
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
```

See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.
@sincev0.1.100
log(const tree: immaculata.LiveTreetree.
LiveTree.files: Map<string, {
    path: string;
    content: Buffer;
    version: number;
}>
files.
Map<string, { path: string; content: Buffer; version: number; }>.get(key: string): {
    path: string;
    content: Buffer;
    version: number;
} | undefined
Returns a specified element from the Map object. If the value that is associated to the provided key is an object, then you will get a reference to that object and any change made to that object will effectively modify it inside the Map.
@returnsReturns the element associated with the specified key. If no element is associated with the specified key, undefined is returned.
get('/index.html')?.content: Buffer<ArrayBufferLike> | undefinedcontent)

Hot reloading

To keep its files up to date, use tree.watch, which uses Chokidar and takes its options mandatorily.

const tree: immaculata.LiveTreetree.LiveTree.watch(opts: ChokidarOptions, onchange: (paths: Set<string>) => void): voidwatch({}, (paths: Set<string>paths) => {
  var console: Console
The `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.

The module exports two specific components:

* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module.

_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for
more information.

Example using the global `console`:

```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```

Example using the `Console` class:

```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```
@see[source](https://github.com/nodejs/node/blob/v22.x/lib/console.js)
console.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)
Prints to `stdout` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)).

```js
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
```

See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.
@sincev0.1.100
log('changed paths:', paths: Set<string>paths)
  // maybe do something
})

Importing live modules

To import files within the given tree, use tree.enableModules.

This is useful for code sharing at build time and in the browser.

const tree: immaculata.LiveTreetree.LiveTree.enableModules(transformJsx?: immaculata.JsxTransformer): voidenableModules()
const const exports: anyexports = await import('./site/foo.ts') as any

Module invalidation

Using tree.enableModules() also invalidates modules that have changed and any modules that depended on them, so that importing them again will re-run their code:

// @filename: test.js
import("./site/foo.js")
// change & save site/foo.js
// then import again:
import("./site/foo.js")

// @filename: site/foo.js
import "./bar.js"
var console: Console
The `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.

The module exports two specific components:

* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module.

_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for
more information.

Example using the global `console`:

```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```

Example using the `Console` class:

```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```
@see[source](https://github.com/nodejs/node/blob/v22.x/lib/console.js)
console.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)
Prints to `stdout` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)).

```js
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
```

See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.
@sincev0.1.100
log('in foo') // prints twice

// @filename: site/bar.js
var console: Console
The `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.

The module exports two specific components:

* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module.

_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for
more information.

Example using the global `console`:

```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```

Example using the `Console` class:

```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```
@see[source](https://github.com/nodejs/node/blob/v22.x/lib/console.js)
console.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)
Prints to `stdout` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)).

```js
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
```

See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.
@sincev0.1.100
log('in bar') // prints twice

So if you import site/foo.ts which imports site/bar.ts, and change site/bar.ts in your editor, importing site/foo.ts will re-eval both modules.

This can be very useful for speeding up development time of large codebases by only reloading a portion of them when they change.

This module invalidation is done through Node's official module hooks, which means it works natively within Node's module system.

JSX at build time

This optionally takes a JSX/TSX transformer so that you can use .jsx/.tsx files at build time. Helpers are provided for convenience.

// just stringifies JSX
const tree: immaculata.LiveTreetree.LiveTree.enableModules(transformJsx?: immaculata.JsxTransformer): voidenableModules(import immaculataimmaculata.const transformModuleJsxToStrings: immaculata.JsxTransformertransformModuleJsxToStrings)

// defers to your code at <tree.root>/jsx-node.ts
const tree: immaculata.LiveTreetree.LiveTree.enableModules(transformJsx?: immaculata.JsxTransformer): voidenableModules(import immaculataimmaculata.const transformModuleJsxToRootJsx: immaculata.JsxTransformertransformModuleJsxToRootJsx)

// point it to whatever import-path you want
const tree: immaculata.LiveTreetree.LiveTree.enableModules(transformJsx?: immaculata.JsxTransformer): voidenableModules(import immaculataimmaculata.function makeModuleJsxTransformer(jsxImportSource: (...args: Parameters<immaculata.JsxTransformer>) => string): immaculata.JsxTransformermakeModuleJsxTransformer(
  (treeRoot: stringtreeRoot, path: stringpath, src: stringsrc, isTs: booleanisTs) => treeRoot: stringtreeRoot + '/my/jsx/impl.ts')
)

const const exports: anyexports = await import('./site/foo.tsx') as any

This could be useful for code sharing, depending on your setup.

File preprocessors

Before using as a website, preprocessing of a tree is useful:

const const outfiles: Map<string, string | Buffer<ArrayBufferLike>>outfiles = await const tree: immaculata.LiveTreetree.LiveTree.processFiles(fn: (pipeline: immaculata.Pipeline) => void | Promise<void>): Promise<Map<string, string | Buffer<ArrayBufferLike>>>processFiles(files: immaculata.Pipelinefiles => {

  files: immaculata.Pipelinefiles.Pipeline.with(regex: RegExp | string): immaculata.Pipelinewith(/\.d\.ts$/).Pipeline.remove(): voidremove()

  files: immaculata.Pipelinefiles.Pipeline.with(regex: RegExp | string): immaculata.Pipelinewith(/\.tsx?$/).Pipeline.do(fn: (file: MemFile) => void): voiddo(f: MemFilef => {
    f: MemFilef.MemFile.path: stringpath = f: MemFilef.MemFile.path: stringpath.
String.replace(searchValue: {
    [Symbol.replace](string: string, replaceValue: string): string;
}, replaceValue: string): string (+3 overloads)
Passes a string and 
{@linkcode 
replaceValue
}
 to the `[Symbol.replace]` method on 
{@linkcode 
searchValue
}
. This method is expected to implement its own replacement algorithm.
@paramsearchValue An object that supports searching for and replacing matches within a string.@paramreplaceValue The replacement text.
replace(/\.tsx?$/, '.js')
    f: MemFilef.MemFile.text: stringtext = const precompileJsx: (s: string) => stringprecompileJsx(f: MemFilef.MemFile.text: stringtext)
  })

  files: immaculata.Pipelinefiles.Pipeline.with(regex: RegExp | string): immaculata.Pipelinewith(/\.css$/).Pipeline.do(fn: (file: MemFile) => void): voiddo(f: MemFilef => f: MemFilef.MemFile.text: stringtext = const minifyCss: (s: string) => stringminifyCss(f: MemFilef.MemFile.text: stringtext))

  files: immaculata.Pipelinefiles.Pipeline.with(regex: RegExp | string): immaculata.Pipelinewith(/\.html$/).Pipeline.do(fn: (file: MemFile) => void): voiddo(f: MemFilef => f: MemFilef.MemFile.text: stringtext = const addCopyright: (s: string) => stringaddCopyright(f: MemFilef.MemFile.text: stringtext))
  files: immaculata.Pipelinefiles.Pipeline.with(regex: RegExp | string): immaculata.Pipelinewith(/\.js$/).Pipeline.do(fn: (file: MemFile) => void): voiddo(f: MemFilef => f: MemFilef.MemFile.text: stringtext = const addCopyright: (s: string) => stringaddCopyright(f: MemFilef.MemFile.text: stringtext))

})

Writing output to disk

When publishing to e.g. GitHub Pages:

const const outfiles: Map<string, string | Buffer<ArrayBufferLike>>outfiles = await const tree: immaculata.LiveTreetree.LiveTree.processFiles(fn: (pipeline: immaculata.Pipeline) => void | Promise<void>): Promise<Map<string, string | Buffer<ArrayBufferLike>>>processFiles(files: immaculata.Pipelinefiles => {
  // ...
})
import immaculataimmaculata.function generateFiles(out: Map<string, Buffer | string>, dry?: boolean, outDir?: string): void
Put files from `LiveTree.files` into `<outDir>/**`

`outDir` defaults to `docs` for GH Pages compatibility.
generateFiles(const outfiles: Map<string, string | Buffer<ArrayBufferLike>>outfiles)

Running a dev server

For local development:

async function function process(): Promise<Map<string, string | Buffer<ArrayBufferLike>>>process() {
  return const tree: immaculata.LiveTreetree.LiveTree.processFiles(fn: (pipeline: immaculata.Pipeline) => void | Promise<void>): Promise<Map<string, string | Buffer<ArrayBufferLike>>>processFiles(files: immaculata.Pipelinefiles => {
    // ...
  })
}

const const server: immaculata.DevServerserver = new import immaculataimmaculata.constructor DevServer(port: number, hmrPath?: string): immaculata.DevServer
Simple, robust dev server compatible with LiveTree.

Customizable SSE route and POST event handlers.
DevServer(8080, '/reload')
const server: immaculata.DevServerserver.DevServer.files: Map<string, string | Buffer<ArrayBufferLike>> | undefinedfiles = await function process(): Promise<Map<string, string | Buffer<ArrayBufferLike>>>process()

const tree: immaculata.LiveTreetree.LiveTree.watch(opts: ChokidarOptions, onchange: (paths: Set<string>) => void): voidwatch({}, async () => {
  const server: immaculata.DevServerserver.DevServer.files: Map<string, string | Buffer<ArrayBufferLike>> | undefinedfiles = await function process(): Promise<Map<string, string | Buffer<ArrayBufferLike>>>process()
  const server: immaculata.DevServerserver.DevServer.reload: () => booleanreload() // invokes SSE at "/reload" per arg above
})

It could be useful to inject an SSE reloading script into HTML files using the preprocessor you define.

Real world example

This website's source is a good example, since it uses markdown, complex syntax highlighting, and HTML injection.

License

Standard MIT

Special thanks

This project was made possible by Jesus, Mary, and Joseph.