@nxgt/mail-config 0.1.0

package/docs/guide/config.md

@@ -0,0 +1,305 @@
+# The project config
+
+This page is for writing a project's `maizzle.config.ts` with
+`defineMailConfig`: which layer wins, how two layers merge, how the build
+events of several plugins run, and what is refused.
+
+```ts
+// maizzle.config.ts
+import { defineMailConfig } from '@nxgt/mail-config';
+import { alpha, beta } from './plugins';
+
+export default defineMailConfig({
+	plugins: [alpha, beta],
+	vue: { globalProperties: { greeting: 'from the project' } },
+	afterTransform: ({ html }) => `${html}<!-- project -->`,
+});
+```
+
+`maizzle serve` and `maizzle build` load that file as they load any Maizzle
+config, and `defineMailConfig` runs each time the file is loaded, answering a
+plain Maizzle config. That can be more than once: above 50 templates Maizzle 6
+builds in parallel, and each worker loads the file again. Keep the call free
+of side effects. The per-template events (`beforeRender`, `afterRender`,
+`afterTransform`) then run in the workers; `beforeCreate` and `afterBuild` run
+only on the main thread, once per build.
+
+## The signature
+
+```ts
+import type { MaizzleConfig } from '@maizzle/framework';
+
+interface MailPlugin extends MaizzleConfig {
+	readonly name: string;
+	readonly plugins?: never; // a plugin cannot bring others
+}
+
+interface MailConfig extends MaizzleConfig {
+	readonly plugins?: readonly MailPlugin[];
+}
+
+function defineMailConfig(config?: MailConfig): MaizzleConfig;
+
+const baseConfig: Readonly<MaizzleConfig>; // { plaintext: true }, frozen
+```
+
+`config` is your whole Maizzle config plus `plugins`. The answer is a new
+object: neither `config` nor any plugin is changed, and neither `plugins` nor a
+plugin's `name` is passed on to Maizzle.
+
+```ts
+import { defineMailConfig } from '@nxgt/mail-config';
+
+defineMailConfig(); // { plaintext: true }
+defineMailConfig({ plugins: [{ name: 'a', root: 'src' }] }); // { plaintext: true, root: 'src' }
+```
+
+## The layers
+
+Three layers, lowest first; each key of a later layer wins over the same key
+below it:
+
+1. `baseConfig` — `{ plaintext: true }`, a plain-text part next to each HTML
+   file. It is frozen: override it in a layer, never by assigning to it. `dist/`, `public/` copied as static files, and CSS inlined and purged
+   are already Maizzle's defaults, so the base does not repeat them.
+2. Each plugin, in the order of `plugins`.
+3. Everything in `config` but `plugins` — your project.
+
+```ts
+import { defineMailConfig } from '@nxgt/mail-config';
+
+const config = defineMailConfig({
+	plugins: [
+		{ name: 'a', output: { path: 'a', extension: 'htm' }, css: { purge: false } },
+		{ name: 'b', output: { path: 'b' } },
+	],
+	output: { path: 'project' },
+});
+// {
+//   plaintext: true,
+//   output: { path: 'project', extension: 'htm' }, ← the project's path, a's extension
+//   css: { purge: false },
+// }
+```
+
+A plugin overrides the base, and the project overrides a plugin — even to turn
+the plain text back off:
+
+```ts
+defineMailConfig({ plugins: [{ name: 'a', plaintext: false }] }).plaintext; // false
+defineMailConfig({
+	plugins: [{ name: 'a', plaintext: false }],
+	plaintext: { extension: 'text' },
+}).plaintext; // { extension: 'text' }
+```
+
+## How two layers merge
+
+The rule is Maizzle's own — the one its config loader uses to put your file
+over its defaults — with three lists as the exception.
+
+| What | Rule |
+| --- | --- |
+| An object | Merged key by key. The later layer's key wins; a key only an earlier layer sets stays |
+| An array | **Replaced** by the later layer's |
+| `components.source` | **Joined**, in layer order. A single entry (not in an array) counts as one |
+| `vite.plugins` | **Joined**, in layer order |
+| `vue.plugins` | **Joined**, in layer order. When any layer gives a factory, the result is a factory |
+| A build event | **Chained** — [below](#build-events) |
+
+### An array replaces
+
+```ts
+const config = defineMailConfig({
+	plugins: [{ name: 'a', static: { source: ['a/**'], destination: 'a' } }],
+	static: { source: ['project/**'] },
+});
+config.static; // { source: ['project/**'], destination: 'a' }
+```
+
+The same holds against Maizzle's defaults, which sit under every layer: a
+plugin that sets `content` replaces `emails/**/*.{vue,md}`, and one that sets
+`static.source` replaces `public/**/*.*`.
+
+### Three lists are joined
+
+Under Maizzle's rule, two plugins that each bring components would keep only
+the last one's. These three are added to instead:
+
+```ts
+const viteA = { name: 'vite-a' };
+const viteB = { name: 'vite-b' };
+
+const config = defineMailConfig({
+	plugins: [
+		{
+			name: 'a',
+			components: { source: { path: '/abs/a', prefix: 'A' } },
+			vite: { plugins: [viteA], base: '/a' },
+		},
+		{ name: 'b', vite: { plugins: [viteB] } },
+	],
+	components: { source: ['components-extra'] },
+});
+config.components; // { source: [{ path: '/abs/a', prefix: 'A' }, 'components-extra'] }
+config.vite; // { base: '/a', plugins: [viteA, viteB] }
+```
+
+A `null` in one of the three sets nothing, as in Maizzle's own merge — it
+neither empties the list nor ends up in it:
+
+```ts
+const config = defineMailConfig({
+	plugins: [{ name: 'a', components: { source: ['a'] } }],
+	components: { source: null as never },
+});
+config.components; // { source: ['a'] }
+```
+
+Your own `components/` folder does not need to be in `components.source`:
+Maizzle always reads it, whatever the list holds, so a component there is
+found whatever the plugins bring.
+
+`vue.plugins` may be a list or a factory, `() => Plugin[]`, which Maizzle calls
+for each render so a stateful Vue plugin starts fresh. When every layer gives a
+list, the lists are joined; when any gives a factory, the result is a factory
+that calls each layer's factory and joins what they answer, in layer order:
+
+```ts
+const one = { install() {} };
+const two = { install() {} };
+
+const config = defineMailConfig({
+	plugins: [{ name: 'a', vue: { plugins: () => [one] } }],
+	vue: { plugins: [two], globalProperties: { x: 1 } },
+});
+const plugins = config.vue?.plugins as () => unknown[];
+plugins(); // [one, two] — a's factory called again on every call
+config.vue?.globalProperties; // { x: 1 }
+```
+
+## Build events
+
+Maizzle keeps **one** function per build event: under a plain merge, the last
+layer's `beforeRender` would replace every other. `defineMailConfig` hands
+Maizzle one function per event that runs every layer's handler, in layer
+order — the base, each plugin in order, then the project — each awaited before
+the next. An event only one layer sets is handed to Maizzle as it is.
+
+Maizzle fires them in this order:
+
+| Event | When | Parameters | What a returned string does |
+| --- | --- | --- | --- |
+| `beforeCreate` | Once, before any template | `{ config }` | Nothing |
+| `beforeRender` | Before each template renders | `{ config, template }` | Replaces `template.source`; the next handler reads the new one |
+| `afterRender` | After each render, before the transformers | `{ config, template, html }` | Becomes the `html` the next handler receives |
+| `afterTransform` | After the transformers, on each template | `{ config, template, html }` | Becomes the `html` the next handler receives |
+| `afterBuild` | Once, after every template | `{ config, files }` | Nothing |
+
+A handler that returns nothing (or anything but a string) leaves the source or
+the HTML as it was.
+
+### `beforeRender`
+
+```ts
+import { defineMailConfig } from '@nxgt/mail-config';
+
+export default defineMailConfig({
+	plugins: [
+		{ name: 'a', beforeRender: ({ template }) => `${template.source} a` },
+		{ name: 'b', beforeRender: ({ template }) => { console.log(template.source); } }, // 'source a'
+	],
+	beforeRender: async ({ template }) => `${template.source} project`,
+});
+// a template whose source is 'source' renders 'source a project'
+```
+
+### `afterRender` and `afterTransform`
+
+```ts
+export default defineMailConfig({
+	plugins: [
+		{ name: 'a', afterTransform: ({ html }) => `${html}a` },
+		{ name: 'b', afterTransform: () => undefined }, // keeps what a answered
+	],
+	afterTransform: async ({ html }) => `${html}p`,
+});
+// '<p>' comes out as '<p>ap'
+```
+
+Each handler receives the `html` the previous one answered; the `html` Maizzle
+passed in is not changed.
+
+### `beforeCreate` and `afterBuild`
+
+```ts
+export default defineMailConfig({
+	plugins: [
+		{ name: 'a', afterBuild: async () => { /* runs first */ } },
+		{ name: 'b', afterBuild: async () => { /* runs once a's has settled */ } },
+	],
+	afterBuild: async ({ files }) => { /* runs last, with every file written */ },
+});
+```
+
+### A throw stops the chain
+
+A handler that throws, or rejects, stops there: the handlers after it do not
+run, and the error reaches Maizzle unchanged, which fails the build with it.
+Nothing is caught or logged on the way.
+
+```ts
+export default defineMailConfig({
+	plugins: [
+		{
+			name: 'a',
+			beforeRender: () => {
+				throw new Error('catalogue broken');
+			},
+		},
+	],
+	beforeRender: () => {
+		/* never runs */
+	},
+});
+```
+
+## Errors
+
+A mistake in how the config is wired is a bare `TypeError`, thrown by
+`defineMailConfig` each time `maizzle.config.ts` is loaded — the first time
+before any template is built, so the build stops there. A message names the
+plugin by its `name`, or by its index when it has none. Several are also
+refused at compile time — a plugin without a `name`, `plugins` that is not a
+list, a build event that is not a function, a plugin that lists plugins; the
+count is in the [README](../../README.md#type-safety-counted).
+
+| Message | Cause |
+| --- | --- |
+| `defineMailConfig: config must be an object, as { plugins, ...maizzleConfig }` | `config` is `null`, an array, or not an object |
+| `defineMailConfig: plugins must be an array` | `plugins` is set to something else |
+| `defineMailConfig: plugins[0] must be a plugin object, as { name, ...config } — was it called?` | An entry is not an object — usually a plugin factory listed without calling it: `plugins: [brand]` for `plugins: [brand()]` |
+| `defineMailConfig: plugins[1] has no name — a plugin is { name, ...config }` | An entry has no `name`, or a blank one |
+| `defineMailConfig: plugin "a" lists plugins — a plugin cannot bring others; list them in the project` | A plugin sets `plugins`: plugins do not nest |
+| `defineMailConfig: two plugins are named "i18n" — is one listed twice?` | Two entries share a `name` |
+| `defineMailConfig: plugin "a": afterBuild must be a function` | A plugin sets a build event to something other than a function |
+| `defineMailConfig: beforeRender must be a function` | The project sets a build event to something other than a function |
+
+```ts
+import { defineMailConfig } from '@nxgt/mail-config';
+import { brand } from './plugins/brand'; // a factory: brand(options) answers the plugin
+
+export default defineMailConfig({
+	plugins: [brand], // TypeError: defineMailConfig: plugins[0] must be a plugin object, … — was it called?
+});
+```
+
+Each message says where the problem is, never a value from your config. A
+plugin checked by `defineMailPlugin` in its own package is refused there, with
+`defineMailPlugin: plugin …` messages — see
+[Writing a plugin](plugins.md#errors).
+
+## See also
+
+- [Writing a plugin](plugins.md) — what goes in a plugin, and `defineMailPlugin`.
+- [Production](production.md) — the same layering, for `maizzle.config.production.ts`.

package/docs/guide/plugins.md

@@ -0,0 +1,280 @@
+# Writing a plugin
+
+This page is for shipping part of a Maizzle config in a package — components,
+global properties, build hooks — so a project adds it with one line in
+`plugins`.
+
+```ts
+// brand.ts in a package, say `acme-mail-brand`, next to its components/ folder
+import { fileURLToPath } from 'node:url';
+import { defineMailPlugin } from '@nxgt/mail-config';
+
+export const brand = defineMailPlugin({
+	name: 'brand',
+	components: {
+		source: [{ path: fileURLToPath(new URL('./components', import.meta.url)), prefix: 'Brand' }],
+	},
+	vue: { globalProperties: { company: 'Example Inc.' } },
+	afterTransform: ({ html }) => `${html}<!-- brand -->`,
+});
+```
+
+```ts
+// maizzle.config.ts, in the project
+import { defineMailConfig } from '@nxgt/mail-config';
+import { brand } from 'acme-mail-brand';
+
+export default defineMailConfig({ plugins: [brand] });
+```
+
+```vue
+<!-- emails/welcome.vue -->
+<template>
+  <Html>
+    <Body>
+      <Container>
+        <Text>Welcome to {{ company }}.</Text>
+        <BrandFooter />
+      </Container>
+    </Body>
+  </Html>
+</template>
+```
+
+`<BrandFooter>` is the package's `components/footer.vue`; `{{ company }}` is
+the global property; every built file ends with `<!-- brand -->`.
+
+## The signature
+
+```ts
+import type { MaizzleConfig } from '@maizzle/framework';
+
+interface MailPlugin extends MaizzleConfig {
+	readonly name: string;
+	readonly plugins?: never; // a plugin cannot bring others
+}
+
+function defineMailPlugin(plugin: MailPlugin): MailPlugin;
+```
+
+A plugin is any Maizzle config key, plus a `name`. `defineMailPlugin` answers
+the object it is given, unchanged; it runs the checks `defineMailConfig` would
+run, so a mistake throws where the plugin is written — in the package, when it
+loads, with a `defineMailPlugin: plugin …` message — and not in each project
+that lists it. See [Errors](#errors). It also types the export as
+`MailPlugin`, so the package's declarations name it.
+
+A plain object `{ name, ...config }` in `plugins` works as well:
+`defineMailPlugin` is for a plugin written in one place and used in another.
+
+## `name`
+
+Names the plugin in an error, and must be unique in a project: two plugins with
+the same `name` are refused, since that is usually one plugin listed twice. It
+is not passed to Maizzle.
+
+```ts
+defineMailPlugin({ name: 'brand', plaintext: false }); // answers the same object
+defineMailPlugin({ output: {} } as never);
+// TypeError: defineMailPlugin: plugin has no name — a plugin is { name, ...config }
+```
+
+## Components, under a prefix
+
+Point `components.source` at a folder **inside the package**, as an absolute
+path, with a `prefix`:
+
+```ts
+import { fileURLToPath } from 'node:url';
+import { defineMailPlugin } from '@nxgt/mail-config';
+
+const here = (path: string) => fileURLToPath(new URL(path, import.meta.url));
+
+export const brand = defineMailPlugin({
+	name: 'brand',
+	components: { source: [{ path: here('./components'), prefix: 'Brand' }] },
+});
+```
+
+- **Absolute.** Maizzle resolves a relative `components.source` against the
+  directory `maizzle` runs in — the project, where `./components` is the
+  project's own folder, not the package's. `new URL(…, import.meta.url)` is
+  relative to the plugin's file wherever the package is installed.
+- **Prefixed.** `prefix: 'Brand'` makes `footer.vue` `<BrandFooter>`, so the
+  package never shadows Maizzle's own components (`<Button>`) or the project's.
+- **Joined, not replaced.** Every plugin's `components.source` is kept, in the
+  order of `plugins`, then the project's — see
+  [The project config](config.md#three-lists-are-joined).
+- **Shipped.** The folder must be in the package's `files`, or it is not in
+  the tarball:
+
+```json
+{
+	"files": ["dist", "components", "README.md", "package.json", "LICENSE"]
+}
+```
+
+When the plugin is compiled to `dist/`, `import.meta.url` is the built file's:
+point the path at where the folder sits relative to `dist/index.js`
+(`'../components'`).
+
+## Global properties
+
+`vue.globalProperties` makes a value available in every template, with no
+import. It is an object, so it merges key by key: a later plugin's key wins
+over an earlier one's, the project's over every plugin's, and a key only one
+layer sets stays.
+
+```ts
+import { defineMailConfig, defineMailPlugin } from '@nxgt/mail-config';
+
+const alpha = defineMailPlugin({
+	name: 'alpha',
+	vue: { globalProperties: { greeting: 'from alpha', origin: 'alpha' } },
+});
+const beta = defineMailPlugin({
+	name: 'beta',
+	vue: { globalProperties: { greeting: 'from beta' } },
+});
+
+export default defineMailConfig({
+	plugins: [alpha, beta],
+	vue: { globalProperties: { greeting: 'from the project' } },
+});
+// {{ greeting }} / {{ origin }} renders 'from the project / alpha'
+```
+
+## Hooks
+
+A plugin sets any of Maizzle's five build events — `beforeCreate`,
+`beforeRender`, `afterRender`, `afterTransform`, `afterBuild` — with Maizzle's
+own parameter types. It never sees the other layers' handlers: each runs in
+turn, and a string it returns is what the next one reads. The table of events
+is in [The project config](config.md#build-events).
+
+```ts
+import { defineMailPlugin } from '@nxgt/mail-config';
+
+export const tracking = defineMailPlugin({
+	name: 'tracking',
+	// replaces the template's source for the handlers after it, and for the render
+	beforeRender: ({ template }) => template.source.replaceAll('[[year]]', String(new Date().getFullYear())),
+	// the html the next handler receives, and in the end the file written
+	afterTransform: ({ html }) => html.replace('</body>', '<!-- sent by Example Inc. --></body>'),
+});
+```
+
+A hook that finds the project wrong **throws**: the handlers after it do not
+run, and Maizzle fails the build with the error. Do not log and return.
+
+## The order of `plugins` matters
+
+Plugins are layered in the order listed, and their hooks run in that order.
+Two plugins that each rewrite what the other wrote give a different result the
+other way round:
+
+```ts
+import { defineMailConfig, defineMailPlugin } from '@nxgt/mail-config';
+
+/** Rewrites `[[mark]]` to `[[alpha]]`, which only beta knows how to finish. */
+const alpha = defineMailPlugin({
+	name: 'alpha',
+	beforeRender: ({ template }) => template.source.replace('[[mark]]', '[[alpha]]'),
+});
+
+/** Finishes what alpha started. */
+const beta = defineMailPlugin({
+	name: 'beta',
+	beforeRender: ({ template }) => template.source.replace('[[alpha]]', 'alpha then beta'),
+});
+
+export default defineMailConfig({ plugins: [alpha, beta] }); // [[mark]] → 'alpha then beta'
+// plugins: [beta, alpha] leaves '[[alpha]]' in the e-mail
+```
+
+A plugin that depends on another's output says so in its README, and names
+which one comes first. The same order decides which plugin's key wins: the
+later one.
+
+## A plugin with options
+
+A package usually exports a function that takes options and answers the
+plugin. Check the options there, and throw a bare `TypeError` for a wrong one —
+a wiring mistake, raised when the config loads, never in the middle of a build:
+
+```ts
+import { fileURLToPath } from 'node:url';
+import { defineMailPlugin, type MailPlugin } from '@nxgt/mail-config';
+
+export interface BrandOptions {
+	/** Shown in every template as {{ company }}. */
+	readonly company: string;
+}
+
+export function brand(options: BrandOptions): MailPlugin {
+	if (typeof options?.company !== 'string' || options.company.trim() === '') {
+		throw new TypeError('brand: company must be a non-empty string');
+	}
+	return defineMailPlugin({
+		name: 'brand',
+		components: {
+			source: [{ path: fileURLToPath(new URL('../components', import.meta.url)), prefix: 'Brand' }],
+		},
+		vue: { globalProperties: { company: options.company } },
+	});
+}
+```
+
+```ts
+// maizzle.config.ts
+export default defineMailConfig({ plugins: [brand({ company: 'Example Inc.' })] });
+```
+
+Listing the factory without calling it — `plugins: [brand]` — is refused by
+`defineMailConfig` with `plugins[0] must be a plugin object, … — was it
+called?`.
+
+## What a plugin cannot do
+
+- **Bring other plugins.** `MailPlugin` declares `plugins?: never`, so a
+  plugin that sets `plugins` is a type error, and a `TypeError` at load time
+  (`plugin "a" lists plugins — a plugin cannot bring others; list them in the
+  project`). A project lists every plugin it uses, so their order is visible
+  in one place.
+- **Win over the project.** The project's config is always the top layer.
+- **Add to an array other than the three joined lists.** A plugin that sets
+  `content` or `static.source` replaces Maizzle's default for it, and is
+  replaced by a later layer that sets it.
+
+## Errors
+
+`defineMailPlugin` throws a bare `TypeError` when the module that calls it
+loads. Its messages name the plugin by its `name`, or `plugin` when it has
+none:
+
+| Message | Cause |
+| --- | --- |
+| `defineMailPlugin: plugin must be a plugin object, as { name, ...config } — was it called?` | The argument is not an object — `null`, an array, a function |
+| `defineMailPlugin: plugin has no name — a plugin is { name, ...config }` | No `name`, or a blank one |
+| `defineMailPlugin: plugin "a" lists plugins — a plugin cannot bring others; list them in the project` | The plugin sets `plugins` |
+| `defineMailPlugin: plugin "a": beforeRender must be a function` | A build event set to something other than a function |
+
+```ts
+import { defineMailPlugin } from '@nxgt/mail-config';
+
+export const broken = defineMailPlugin({
+	name: 'a',
+	beforeRender: 'x' as never,
+}); // TypeError: defineMailPlugin: plugin "a": beforeRender must be a function
+```
+
+The same mistakes in a plain object listed in `plugins` are refused by
+`defineMailConfig`, as `defineMailConfig: plugins[1] …` — see
+[The project config](config.md#errors). Two plugins with the same `name` can
+only be seen there, in the project.
+
+## See also
+
+- [The project config](config.md) — the layers, the merge rules, the chained
+  events and every error.
+- [Production](production.md) — a hook that only runs in the production build.