first commit

docs/localization/i18n/i18n-backend-fs-multifile/src/factory/factory.md

@@ -0,0 +1,72 @@
+# `factory.ts` — `multiFileFsBackend()`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Builder-style entry point that returns a fresh `MultiFileFsBackend`
+per call. Functionally identical to `new MultiFileFsBackend(options)`,
+but reads naturally in pipelines and configuration objects where the
+caller is composing a backend chain alongside `memoryBackend()`,
+`storageBackend()`, `httpBackend()`, and `chainedBackend()` — every
+backend in the family ships a matching factory function for symmetry.
+
+The factory has no internal state — every invocation returns a brand-new
+instance. Options are validated by the same Zod schema as the
+constructor; bad options throw `I18nError(I18N.INVALID_OPTIONS)`. There
+is no caching, no singleton, and no hidden configuration: the factory
+exists purely to flip the calling style from `new C(opts)` to
+`factory(opts)` for ergonomic chain composition.
+
+## Features
+
+- Returns a fresh `MultiFileFsBackend` on every call.
+- Forwards all options unchanged into the class constructor.
+- Same validation surface — bad options throw `INVALID_OPTIONS`.
+- Zero shared state, zero side effects.
+
+## Usage: Basic Example
+
+```ts
+import { multiFileFsBackend } from "@suaveplan/i18n-backend-fs-multifile";
+
+const backend = multiFileFsBackend({ root: "./locales" });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { chainedBackend } from "@suaveplan/i18n-backend-chained";
+import { multiFileFsBackend } from "@suaveplan/i18n-backend-fs-multifile";
+import { memoryBackend } from "@suaveplan/i18n-backend-memory";
+
+// Server-side: hot in-memory cache → fall through to disk on miss.
+const chain = chainedBackend([
+    memoryBackend(),
+    multiFileFsBackend({ root: "./locales", watch: true }),
+]);
+
+await chain.init({
+    catalogName: "app",
+    emitLoaded: () => {},
+});
+
+const record = await chain.read("en", "auth");
+```
+
+## API Reference
+
+- `multiFileFsBackend(options: MultiFileFsBackendOptions): MultiFileFsBackend`:
+  returns a new `MultiFileFsBackend` instance. Throws
+  `I18nError(I18N.INVALID_OPTIONS)` on schema failure or when
+  `layout: "glob"` is supplied without `globPattern`.
+
+## Implementation Notes
+
+- The factory is a thin wrapper — the line count is intentional. The
+  factory exists for symmetry with the rest of the i18n backend
+  family, where every concrete backend ships both a class export and
+  a `<thing>Backend()` factory function.
+- The factory is server-tier — declaring this package's `engines.node`
+  at the package boundary covers the factory and the class equally.