@joetjen/cooper-fastify 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Jan Oetjen
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,209 @@
-# Temporary Holding Version
+# cooper-fastify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+cooper-fastify is a [Fastify](https://fastify.dev) plugin that loads your
+application's [CASC](https://github.com/joetjen/cooper/blob/main/guides/casc/CASC.md)
+configuration once, at startup, and puts it on `fastify.config`. It also
+gives the server's own options -- body limit, timeouts, logger, TLS --
+to the `Fastify()` factory from the same document.
+
+Fastify has no configuration system of its own. This plugin takes the
+place of `@fastify/env` and of `dotenv`: `.env` files are read by
+[`cooper`](https://github.com/joetjen/node-cooper) itself. The loading
+and reading are [`cooper-config`](https://github.com/joetjen/node-cooper-config)'s,
+so `fastify.config.get(...)` and `require('@joetjen/cooper-config').get(...)` read
+the same configuration.
+
+```text
+# config/config.casc
+#@version = 1.0
+
+fastify {
+  bodyLimit      = 1MiB
+  requestTimeout = 30s
+  trustProxy     = true
+  logger { level = "info" }
+  https {
+    key  = !file("certs/server.key")
+    cert = !file("certs/server.crt")
+  }
+  listen { port = 8443, host = "0.0.0.0" }
+}
+
+db {
+  host      = "db.internal"
+  *password = ${DB_PASSWORD}
+}
+
+import "${COOPER_ENV}/*.casc"
+```
+
+```js
+import Fastify from 'fastify';
+import cooper, { serverOptions, listenOptions } from '@joetjen/cooper-fastify';
+
+const app = Fastify(await serverOptions());   // loads config/config.casc, once
+await app.register(cooper);                   // fastify.config
+
+app.get('/db', async (request) => ({ host: request.server.config.get('db.host') }));
+
+await app.listen(listenOptions());
+```
+
+## Install
+
+```sh
+npm install @joetjen/cooper-fastify
+```
+
+`fastify` 5 is a peer dependency, so your own is used. `cooper-config`
+and `cooper` come along. You need Node.js 20 or later. `require` works
+the same way as `import`.
+
+## The plugin
+
+```js
+await app.register(cooper, options?);
+```
+
+Registering it loads the configuration and decorates the instance with
+`config`. The plugin is wrapped with `fastify-plugin`, so the
+configuration lands on the instance that registers it, and every plugin
+and route below sees it.
+
+| | |
+| --- | --- |
+| options given | loads with them, cooper-config's load options (`path`, `root`, `env`, `dotenvDir`, `modules`, `tags`, ...) |
+| no options, something loaded | reads that: by `serverOptions()`, the preload entry or `cooper-config` itself |
+| no options, nothing loaded | loads `config/config.casc` under the project root |
+| an unknown option | `TypeError` |
+| the document does not load | `ready()` rejects with `CooperConfigError`; the server never starts |
+| `prefix`, `logLevel`, `logSerializers` | Fastify's, left to Fastify |
+
+The project root is the directory of the nearest `package.json` above
+the working directory.
+
+## Reading: `fastify.config`
+
+```js
+app.config.get('db.port', 5432);     // the value, or the fallback when there is none
+app.config.require('db.host');       // the value, or a CooperConfigError naming the path
+app.config.has('db.replica');        // whether anything, null included, is there
+app.config.all();                    // the whole configuration
+request.server.config.get('db.host') // the same, in a route
+```
+
+Paths are dotted (`'db.pool.size'`) or an array of segments for a key
+holding a dot (`['dotted.key', 'inner']`). Every value is deep-frozen,
+and so is `fastify.config`. Byte sizes arrive as bytes and durations as
+milliseconds; the [`cooper-config` README](https://github.com/joetjen/node-cooper-config#conversion)
+has the full table, and how each block's secrets arrive.
+
+TypeScript knows `fastify.config` once the package is imported:
+
+```ts
+const host = app.config.require<string>('db.host');
+```
+
+## The server's options: `serverOptions()` and `listenOptions()`
+
+Fastify takes its server options once, when `Fastify()` creates the
+app, before any plugin runs. So the plugin cannot set them, and
+`serverOptions()` reads them first:
+
+```js
+const app = Fastify(await serverOptions(options?));
+await app.listen(listenOptions());
+```
+
+- `serverOptions()` loads the configuration by the plugin's rule and
+  returns the `fastify` block without its `listen` block. The plugin
+  registered afterwards without options reads the same load.
+- `listenOptions()` returns the `fastify.listen` block. It loads
+  nothing.
+- Both return fresh, mutable objects, and an empty one when there is no
+  block.
+- The keys are Fastify's own, camel case included.
+
+### Code: `!module`
+
+Options that are functions or objects -- `genReqId`, a log `stream`, a
+`loggerInstance`, `querystringParser` -- are named with CASC's `!module`
+and mapped in code:
+
+```text
+fastify {
+  genReqId = !module("App.RequestId")
+}
+```
+
+```js
+const app = Fastify(await serverOptions({
+  modules: { 'App.RequestId': './lib/request-id.js' },   // its default export
+  // or:  { 'App.RequestId': genReqId }                  // the value itself
+}));
+```
+
+A document can only choose among the names the application mapped. It
+can never name a file of code, not even through `${...}`. A `!module`
+anywhere in the block is resolved. This is why `serverOptions()` is
+asynchronous: a mapped path is imported.
+
+### Files: `!file`
+
+`!file("path")` is a file's contents, as UTF-8 text, for options that
+take contents rather than a path -- `https.key`, `https.cert`,
+`https.ca`:
+
+```text
+fastify {
+  https {
+    key  = !file("certs/server.key")     # relative to the project root
+    cert = !file("${TLS_CERT}")          # or a path from the environment
+  }
+}
+```
+
+- An absolute path is read as it is.
+- A file that is not there fails the load, naming it.
+- `!file` works everywhere in the document, not only in `fastify`.
+- A `file` tag of your own, passed in `tags`, replaces it.
+- It is cooper-fastify's tag, not part of CASC: a document using it
+  loads only where it is registered.
+- An application loading with `cooper-config` directly can register it
+  with `tags: { file: fileTag(root) }`.
+
+## Startup without `serverOptions()`
+
+When nothing reads the configuration before the plugin, registering it
+is enough. To load it before any of your code runs, preload it:
+
+```sh
+node --import @joetjen/cooper-fastify/register app.js     # ES modules
+node --require @joetjen/cooper-fastify/register app.js    # CommonJS
+```
+
+Use `@joetjen/cooper-fastify/register` rather than `@joetjen/cooper-config/register`,
+because only this one registers `!file`. A document that does not load
+stops the process with its message and exit code 1.
+
+## Per-environment configuration
+
+`${COOPER_ENV}` names the environment (`dev`, `test`, `prod`), falling
+back to `NODE_ENV`, and `.env.<env>` is chosen by it. See the
+[`cooper-config` README](https://github.com/joetjen/node-cooper-config#per-environment-configuration-cooper_env).
+
+## Development
+
+```sh
+npm install
+npm run precommit
+```
+
+`npm run precommit` type-checks the JSDoc (`tsc --checkJs --noEmit`)
+and the TypeScript declarations, and runs the Mocha suite. See
+[CONTRIBUTING.md](CONTRIBUTING.md) and the
+[cheatsheet](guides/CHEATSHEET.md).
+
+## License
+
+Apache-2.0, see [LICENSE](LICENSE).

package/guides/CHEATSHEET.md

@@ -0,0 +1,65 @@
+# cooper-fastify cheatsheet
+
+## Startup
+
+```js
+import Fastify from 'fastify';
+import cooper, { serverOptions, listenOptions } from '@joetjen/cooper-fastify';
+
+const app = Fastify(await serverOptions(options?));   // loads, once
+await app.register(cooper);                           // fastify.config
+await app.listen(listenOptions());
+```
+
+```sh
+node --import @joetjen/cooper-fastify/register app.js     # or preload: ESM
+node --require @joetjen/cooper-fastify/register app.js    # CJS
+```
+
+## When the configuration is loaded
+
+| Call | Loads |
+| --- | --- |
+| `register(cooper, options)` / `serverOptions(options)` | with `options`, always |
+| `register(cooper)` / `serverOptions()` | nothing if already loaded, else the defaults |
+| `listenOptions()` | never |
+| `@joetjen/cooper-fastify/register` | the defaults, before the application |
+
+| | |
+| --- | --- |
+| options | cooper-config's: `path`, `root`, `env`, `dotenv*`, `resolvers`, `tags`, `importSchemes`, `modules`, `cache`, `watchEnv` |
+| unknown option | `TypeError` |
+| document does not load | `ready()` / `serverOptions()` rejects with `CooperConfigError`; preload exits 1 |
+| no `config/config.casc` | empty configuration |
+
+## Reading
+
+```js
+app.config.get(path, fallback?)    // value, or fallback
+app.config.require(path)           // value, or CooperConfigError
+app.config.has(path)               // true for a present null
+app.config.all()                   // everything, deep-frozen
+request.server.config              // the same, in a route
+```
+
+`path`: `'a.b.c'` or `['dotted.key', 'inner']`.
+
+## The `fastify` block
+
+```text
+fastify {
+  bodyLimit      = 1MiB                     # 1048576
+  requestTimeout = 30s                      # 30000
+  logger { level = "info" }
+  genReqId = !module("App.RequestId")       # mapped in code
+  https { key = !file("certs/server.key") } # the file's text
+  listen { port = 8080, host = "0.0.0.0" }  # listenOptions() only
+}
+```
+
+| | |
+| --- | --- |
+| keys | Fastify's own, camel case |
+| `!module("Name")` | `modules[Name]`: a value as is, a specifier's default export |
+| `!file("path")` | UTF-8 contents; relative to the project root, or absolute; `${...}` allowed |
+| result | fresh, mutable; `{}` without a block |

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@joetjen/cooper-fastify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Jan Oetjen <joetjen.riveting388@passmail.net> (http://joetjen.net)",
+  "description": "A Fastify plugin that loads an application's CASC configuration once, at startup, with cooper-config, and puts it on fastify.config -- the server's own options included.",
+  "homepage": "https://github.com/joetjen/node-cooper-fastify",
+  "type": "module",
+  "main": "./src/cooper-fastify.cjs",
+  "types": "./types/cooper-fastify.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/cooper-fastify.d.ts",
+      "import": "./src/cooper-fastify.js",
+      "require": "./src/cooper-fastify.cjs",
+      "default": "./src/cooper-fastify.cjs"
+    },
+    "./register": {
+      "import": "./src/register.js",
+      "require": "./src/register.cjs",
+      "default": "./src/register.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "types",
+    "guides"
+  ],
+  "license": "Apache-2.0",
+  "directories": {
+    "src": "./src"
+  },
+  "dependencies": {
+    "@joetjen/cooper": "^0.1.1",
+    "@joetjen/cooper-config": "^0.1.0",
+    "fastify-plugin": "^6.0.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "auto-changelog": "^2.6.0",
+    "chai": "^6.2.2",
+    "fastify": "^5.12.5",
+    "mocha": "^12.0.3",
+    "typedoc": "^0.28.20",
+    "typescript": "~6.0"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=9.0.0"
+  },
+  "scripts": {
+    "test": "npx mocha --recursive test/",
+    "autotest": "npx mocha --recursive --watch test/",
+    "typecheck": "npx tsc --checkJs --noEmit && npx tsc --noEmit -p test/types",
+    "precommit": "npm run typecheck && npm test",
+    "docs": "npx typedoc",
+    "version": "npx auto-changelog --package --template keepachangelog && git add CHANGELOG.md"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/joetjen/node-cooper-fastify.git"
+  },
+  "bugs": {
+    "url": "https://github.com/joetjen/node-cooper-fastify/issues",
+    "email": "joetjen.riveting388@passmail.net"
+  },
+  "keywords": [
+    "casc",
+    "cooper",
+    "config",
+    "configuration",
+    "fastify",
+    "fastify-plugin"
+  ]
+}

package/src/cooper-fastify.cjs

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * @fileoverview The plugin: registering it loads the application's CASC
+ * configuration, and `fastify.config` reads it.
+ *
+ * ```js
+ * const app = Fastify(await serverOptions());
+ * await app.register(cooper);
+ * app.config.get('db.host');
+ * ```
+ *
+ * **Fastify has no configuration system of its own**, so there is nothing
+ * to feed and nothing to replace but `@fastify/env`, whose
+ * `fastify.config` this takes the name of. The configuration itself is
+ * `cooper-config`'s, loaded once and process-wide, so `fastify.config` and
+ * a plain `require('@joetjen/cooper-config').get(...)` read the same thing.
+ *
+ * It is wrapped with `fastify-plugin`: a configuration belongs to the
+ * whole application, not to the encapsulation context that happened to
+ * register it.
+ */
+
+const fp = require('fastify-plugin');
+const cooperConfig = require('@joetjen/cooper-config');
+const { ensureLoaded } = require('./load.cjs');
+const { serverOptions, listenOptions } = require('./server-options.cjs');
+const { fileTag } = require('./file-tag.cjs');
+const version = require('./version.cjs');
+
+/**
+ * What `fastify.config` is: cooper-config's four readers, frozen, so no
+ * plugin can swap the configuration out from under the others.
+ * @typedef {Readonly<{get: typeof cooperConfig.get, require: typeof cooperConfig.require, has: typeof cooperConfig.has, all: typeof cooperConfig.all}>} ConfigReader
+ */
+
+/** @type {ConfigReader} */
+const reader = Object.freeze({
+  get: cooperConfig.get,
+  require: cooperConfig.require,
+  has: cooperConfig.has,
+  all: cooperConfig.all,
+});
+
+/**
+ * Loads the configuration and decorates the instance with `config`.
+ *
+ * Its options are cooper-config's load options. Given none, it reads a
+ * configuration already loaded -- by `serverOptions()`, the preload entry
+ * or the application -- and loads the defaults only when there is none.
+ * A document that does not load rejects, so `ready()` does and the server
+ * never starts.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {Record<string, unknown>} options
+ * @returns {Promise<void>}
+ */
+async function cooperFastify(fastify, options) {
+  ensureLoaded(options);
+  fastify.decorate('config', reader);
+}
+
+const plugin = fp(cooperFastify, { name: '@joetjen/cooper-fastify', fastify: '5.x' });
+
+// The CommonJS module is the plugin, as Fastify's plugins are, with the
+// rest of the API on it. `default` and `cooperFastify` are the names a
+// transpiled default import and a named import look for.
+module.exports = plugin;
+module.exports.default = plugin;
+module.exports.cooperFastify = plugin;
+module.exports.serverOptions = serverOptions;
+module.exports.listenOptions = listenOptions;
+module.exports.fileTag = fileTag;
+module.exports.version = version;

package/src/cooper-fastify.js

@@ -0,0 +1,17 @@
+import { createRequire } from 'node:module';
+
+const requireCjs = createRequire(import.meta.url);
+const plugin = requireCjs('./cooper-fastify.cjs');
+
+/** @type {typeof plugin.serverOptions} */
+const serverOptions = plugin.serverOptions;
+/** @type {typeof plugin.listenOptions} */
+const listenOptions = plugin.listenOptions;
+/** @type {typeof plugin.fileTag} */
+const fileTag = plugin.fileTag;
+/** @type {string} */
+const version = plugin.version;
+
+export { plugin as cooperFastify, serverOptions, listenOptions, fileTag, version };
+
+export default plugin;

package/src/file-tag.cjs

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * @fileoverview `!file("...")`: a file's contents as a configuration
+ * value, and the project root a relative path is read from.
+ *
+ * **For the options that take contents rather than a path.** Fastify's
+ * `https` key, certificate and CA are the reason this exists: they are
+ * PEM text, and without the tag they could only be read in code, outside
+ * the configuration that otherwise describes the server.
+ *
+ * **This tag is cooper-fastify's, not CASC's.** A document using it loads
+ * only where it is registered. That is the same bargain the Laravel
+ * adapter's path tags make, and it stays here until a second integration
+ * needs it.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * The project root: the directory of the nearest `package.json` found
+ * walking up from `cwd`, else `cwd` itself.
+ *
+ * The same rule `cooper-config` finds `config/config.casc` by, so a
+ * relative `!file` path and the document are read from one directory.
+ * Repeated here because `cooper-config` does not export it.
+ *
+ * @param {string} [cwd] -- where to start (default `process.cwd()`)
+ * @returns {string} an absolute path
+ */
+function projectRoot(cwd = process.cwd()) {
+  const start = path.resolve(cwd);
+  for (let dir = start; ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    if (path.dirname(dir) === dir) return start;
+  }
+}
+
+/**
+ * The `!file` tag for a project rooted at `root`: it reads the file its
+ * argument names -- relative to `root`, or absolute -- as UTF-8 text.
+ *
+ * Text, not a `Buffer`, because what it is for is text: PEM keys and
+ * certificates, which Fastify and `node:tls` take as strings.
+ *
+ * **The environment may choose the file** (`!file("${TLS_KEY}")`), which
+ * `!module` deliberately does not allow for code: reading a file runs
+ * nothing.
+ *
+ * @param {string} root -- the directory a relative path is read from
+ * @returns {(argument: unknown) => string}
+ * @example
+ *   loadFileSync('config/config.casc', { tags: { file: fileTag(process.cwd()) } });
+ */
+function fileTag(root) {
+  return function file(argument) {
+    if (typeof argument !== 'string') {
+      throw new TypeError(`!file takes a path as a string, not ${typeof argument === 'object' ? String(argument) : JSON.stringify(argument) ?? String(argument)}`);
+    }
+    const absolute = path.resolve(root, argument);
+    try {
+      return fs.readFileSync(absolute, 'utf8');
+    } catch (err) {
+      const code = /** @type {NodeJS.ErrnoException} */ (err).code ?? /** @type {Error} */ (err).message;
+      throw new Error(`cannot read ${absolute} (${code})`);
+    }
+  };
+}
+
+module.exports = { fileTag, projectRoot };

package/src/load.cjs

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * @fileoverview When the configuration is loaded, and with what: the one
+ * rule the plugin, `serverOptions()` and the preload entry share.
+ *
+ * - **Options given: load with them**, whatever was loaded before. They
+ *   are a request for that configuration.
+ * - **No options: read what is loaded**, so `serverOptions(options)`
+ *   followed by `register(cooper)` is one load, not two -- and a load the
+ *   application made with `cooper-config` itself, or through a preload,
+ *   is the one the plugin reads.
+ * - **No options and nothing loaded: load the defaults.**
+ *
+ * Every load registers `!file`, beside the application's own tags.
+ */
+
+const path = require('node:path');
+const cooperConfig = require('@joetjen/cooper-config');
+const { fileTag, projectRoot } = require('./file-tag.cjs');
+
+/**
+ * Fastify's own `register()` options. Fastify hands them to the plugin
+ * along with the rest, and they are not cooper-config's to refuse.
+ */
+const FASTIFY_REGISTER_OPTIONS = ['prefix', 'logLevel', 'logSerializers'];
+
+/**
+ * Loads the configuration by the rule above.
+ * @param {Record<string, unknown>} [options] -- cooper-config's load options, Fastify's register options among them or not
+ * @returns {void}
+ * @throws {TypeError} for an option cooper-config does not know
+ * @throws {import('@joetjen/cooper-config').CooperConfigError} when the document does not load
+ */
+function ensureLoaded(options = {}) {
+  const own = withoutFastifyOptions(options);
+  if (Object.keys(own).length === 0 && isLoaded()) return;
+  cooperConfig.load(withFileTag(own));
+}
+
+/**
+ * `options` without Fastify's own register options.
+ * @param {Record<string, unknown>} options
+ * @returns {Record<string, unknown>}
+ */
+function withoutFastifyOptions(options) {
+  /** @type {Record<string, unknown>} */
+  const own = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (!FASTIFY_REGISTER_OPTIONS.includes(key)) own[key] = value;
+  }
+  return own;
+}
+
+/**
+ * `options` with `!file` among its tags, rooted where the document is
+ * read from. **The application's own `file` tag wins**, as a tag of
+ * cooper's own name does over cooper's built-in.
+ * @param {Record<string, unknown>} options
+ * @returns {Record<string, unknown>}
+ */
+function withFileTag(options) {
+  const root = typeof options.root === 'string' ? path.resolve(options.root) : projectRoot();
+  const file = fileTag(root);
+  const tags = options.tags;
+  if (tags instanceof Map) return { ...options, tags: new Map([['file', file], ...tags]) };
+  return { ...options, tags: { file, .../** @type {Record<string, unknown>} */ (tags ?? {}) } };
+}
+
+/**
+ * Whether a configuration has been loaded in this process. `cooper-config`
+ * answers that only by refusing to read before a load.
+ * @returns {boolean}
+ */
+function isLoaded() {
+  try {
+    cooperConfig.all();
+    return true;
+  } catch (err) {
+    if (err instanceof cooperConfig.CooperConfigError) return false;
+    throw err;
+  }
+}
+
+module.exports = { ensureLoaded, withFileTag };

package/src/register.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+/**
+ * @fileoverview The preload entry: `node --import @joetjen/cooper-fastify/register`
+ * (or `--require`) loads the configuration with its defaults before the
+ * application's own code, `!file` included -- which is why it is not
+ * `@joetjen/cooper-config/register`, whose load does not know the tag.
+ *
+ * A configuration that fails to load stops the process here, with the
+ * error's message and exit code 1 rather than a stack trace: the trace
+ * would point into this library, and what needs fixing is the document.
+ */
+
+const { CooperConfigError } = require('@joetjen/cooper-config');
+const { ensureLoaded } = require('./load.cjs');
+
+try {
+  ensureLoaded();
+} catch (err) {
+  if (!(err instanceof CooperConfigError)) throw err;
+  process.stderr.write(`cooper-fastify: ${err.message}\n`);
+  process.exit(1);
+}

package/src/register.js

@@ -0,0 +1,3 @@
+// The ESM face of `register.cjs`: importing it runs the CJS module once,
+// against the same process-wide store `cooper-config` reads from.
+import './register.cjs';

package/src/server-options.cjs

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * @fileoverview `serverOptions()` and `listenOptions()`: the `fastify`
+ * block, as the `Fastify()` factory and `listen()` take it.
+ *
+ * **The server's options are fixed when it is created**, before any
+ * plugin runs, so the plugin cannot set them. These two read the
+ * configuration first -- `serverOptions()` loading it -- for the factory
+ * call, which is what lets a server's body limit, timeouts and logger live
+ * in the same document as everything else, under the same overlays.
+ *
+ * The keys are Fastify's own, camel case and all: a second spelling of
+ * every option would be one more thing to learn and nothing to gain.
+ * Byte sizes and durations already arrive as bytes and milliseconds, the
+ * units Fastify takes them in.
+ */
+
+const cooperConfig = require('@joetjen/cooper-config');
+const { ModuleRef } = require('@joetjen/cooper');
+const { ensureLoaded } = require('./load.cjs');
+
+/** The block both read. */
+const BLOCK = 'fastify';
+
+/** The sub-block that is `listen()`'s and not the factory's. */
+const LISTEN = 'listen';
+
+/**
+ * The `fastify` block, without its `listen` block, for `Fastify()`.
+ *
+ * Loads the configuration by the plugin's rule (see `load.cjs`): with
+ * `options`, or reading what is loaded when there are none. **Every
+ * `!module("Name")` in the block becomes what the application mapped the
+ * name to**: the value itself, or the default export of the module a
+ * specifier names, which is why this is asynchronous. A document can
+ * choose only among the names the application mapped, never a file of
+ * code.
+ *
+ * @param {import('../types/cooper-fastify.js').CooperFastifyOptions} [options]
+ * @returns {Promise<Record<string, any>>} a fresh, mutable object; empty when there is no `fastify` block
+ * @throws {TypeError} for an option cooper-config does not know
+ * @throws {import('@joetjen/cooper-config').CooperConfigError} when the document does not load
+ * @example
+ *   const app = Fastify(await serverOptions({ modules: { 'App.RequestId': genReqId } }));
+ */
+async function serverOptions(options) {
+  ensureLoaded(/** @type {Record<string, unknown>} */ (options ?? {}));
+  const { [LISTEN]: _listen, ...rest } = /** @type {Record<string, unknown>} */ (cooperConfig.get(BLOCK, {}));
+  return /** @type {Record<string, any>} */ (await thawed(rest));
+}
+
+/**
+ * The `fastify.listen` block, for `listen()`.
+ *
+ * It reads what is loaded and loads nothing: it is called once the app
+ * exists, and by then `serverOptions()` or the plugin has loaded.
+ *
+ * @returns {Record<string, any>} a fresh, mutable object; empty when there is no such block
+ * @throws {import('@joetjen/cooper-config').CooperConfigError} before anything is loaded
+ * @example
+ *   await app.listen(listenOptions());
+ */
+function listenOptions() {
+  return /** @type {Record<string, any>} */ (copy(cooperConfig.get([BLOCK, LISTEN], {})));
+}
+
+/**
+ * A mutable copy of a configuration value with every `ModuleRef` in it
+ * replaced by its target.
+ *
+ * Mutable because Fastify, pino and `node:http` were written for option
+ * objects they may fill in, and the configuration is frozen.
+ *
+ * @param {unknown} value
+ * @returns {Promise<unknown>}
+ */
+async function thawed(value) {
+  if (value instanceof ModuleRef) return target(value);
+  if (Array.isArray(value)) return Promise.all(value.map(thawed));
+  if (isPlain(value)) {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [key, inner] of Object.entries(/** @type {object} */ (value))) out[key] = await thawed(inner);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * What a `!module` names: the mapped value as it is, or, for a specifier,
+ * the module's default export -- what a function or a class is exported
+ * as, from CommonJS and ES modules alike -- else its namespace.
+ * @param {InstanceType<typeof ModuleRef>} ref
+ * @returns {Promise<unknown>}
+ */
+async function target(ref) {
+  const loaded = await ref.load();
+  if (ref.specifier === undefined) return loaded;
+  return loaded !== null && typeof loaded === 'object' && 'default' in loaded ? loaded.default : loaded;
+}
+
+/**
+ * The synchronous copy `listenOptions()` makes: blocks and lists, nothing
+ * resolved.
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function copy(value) {
+  if (Array.isArray(value)) return value.map(copy);
+  if (isPlain(value)) {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [key, inner] of Object.entries(/** @type {object} */ (value))) out[key] = copy(inner);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Whether `value` is a block: a plain or null-prototype object, not one
+ * of cooper's values or anything the application mapped.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlain(value) {
+  if (value === null || typeof value !== 'object') return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+}
+
+module.exports = { serverOptions, listenOptions };

package/src/version.cjs

@@ -0,0 +1,9 @@
+'use strict';
+
+const { version } = require('../package.json');
+
+/**
+ * The installed `cooper-fastify` package version, read from `package.json`.
+ * @type {string}
+ */
+module.exports = version;

package/types/cooper-fastify.d.ts

@@ -0,0 +1,66 @@
+// Types for TypeScript applications. The implementation is JavaScript,
+// checked by `tsc --checkJs`; these say what it gives a TypeScript caller,
+// above all that `fastify.config` exists once the plugin is registered.
+
+import type { FastifyListenOptions, FastifyPluginAsync } from 'fastify';
+
+/** A path into the configuration: `'db.pool.size'`, or segments for a key holding a dot. */
+export type KeyPath = string | readonly string[];
+
+/** What `fastify.config` is: cooper-config's readers. */
+export interface ConfigReader {
+  /** The value at `path`, or `fallback` when there is none. */
+  get<T = any>(path: KeyPath, fallback?: T): T;
+  /** The value at `path`, which must be there. */
+  require<T = any>(path: KeyPath): T;
+  /** Whether anything, `null` included, is at `path`. */
+  has(path: KeyPath): boolean;
+  /** The whole configuration, deep-frozen. */
+  all(): Readonly<Record<string, any>>;
+}
+
+/** cooper-config's load options. */
+export interface CooperFastifyOptions {
+  /** The CASC file; a relative one against the project root (default `config/config.casc`). */
+  path?: string;
+  /** The project root (default: the directory of the nearest `package.json`). */
+  root?: string;
+  env?: Record<string, string>;
+  dotenv?: boolean;
+  dotenvEnv?: string | null;
+  dotenvFiles?: string[];
+  dotenvDir?: string;
+  dotenvOverride?: boolean;
+  resolvers?: Record<string, (...args: any[]) => unknown> | Map<string, (...args: any[]) => unknown>;
+  tags?: Record<string, (argument: any) => unknown> | Map<string, (argument: any) => unknown>;
+  importSchemes?: Record<string, (...args: any[]) => unknown>;
+  /** What each `!module("Name")` means: a value, or a specifier whose default export is used. */
+  modules?: Record<string, unknown> | Map<string, unknown>;
+  cache?: boolean;
+  watchEnv?: boolean;
+}
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    /** The application's configuration, loaded by cooper-fastify. */
+    config: ConfigReader;
+  }
+}
+
+/** The plugin. Registering it loads the configuration and decorates the instance with `config`. */
+declare const cooperFastify: FastifyPluginAsync<CooperFastifyOptions>;
+
+/** The `fastify` block, without `listen`, for the `Fastify()` factory; loads the configuration. */
+export function serverOptions(options?: CooperFastifyOptions): Promise<Record<string, any>>;
+
+/** The `fastify.listen` block, for `listen()`. */
+export function listenOptions(): FastifyListenOptions;
+
+/** The `!file` tag for a project rooted at `root`. */
+export function fileTag(root: string): (argument: unknown) => string;
+
+/** The installed package version. */
+export const version: string;
+
+export { cooperFastify };
+export default cooperFastify;