lumen-framework 3.1.1 → 4.0.0

package/dist/types/packages/server/utils/source-for.d.ts

@@ -1,10 +1,26 @@
-import type { Server$ErrorSource } from '../interfaces';
+import type { ServerErrorSource } from '../interfaces';
 /**
  * Map an internal parameter path to a JSON:API error `source`. Paths under
  * `data` are request document members and become a JSON Pointer
  * (`data.attributes.isPublic` -> `/data/attributes/is-public`); anything else
  * is a query parameter (`page.size` -> `page[size]`).
  *
- * @private
+ * @internal
  */
-export default function sourceFor(path: string): Server$ErrorSource;
+export default function sourceFor(path: string): ServerErrorSource;
+/**
+ * A parameter path as the client writes it, for error messages: request
+ * document members dasherized and dotted (`data.attributes.is-public`), query
+ * parameters in brackets (`filter[created-at]`, `page[size]`).
+ *
+ * @internal
+ */
+export declare function nameFor(path: string): string;
+/**
+ * A member name or relationship path as it appears in documents, keeping a
+ * `sort` value's leading `-` (`-createdAt` -> `-created-at`,
+ * `comments.user` stays dotted). Anything but a string is returned as is.
+ *
+ * @internal
+ */
+export declare function memberPathFor(value: unknown): unknown;

package/dist/types/packages/server/utils/status-for-error.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The status an error is answered with: its own `statusCode`, or `500`.
+ *
+ * @internal
+ */
+export default function statusForError(err: unknown): number;

package/dist/types/packages/server/utils/validate-accept.d.ts

@@ -3,6 +3,6 @@
  * type and *all* instances of it are modified with media type parameters.
  * An Accept header without the JSON:API media type is left alone.
  *
- * @private
+ * @internal
  */
 export default function validateAccept(accept?: string): true;

package/dist/types/packages/server/utils/validate-content-type.d.ts

@@ -1,8 +1,13 @@
 /**
  * JSON:API 1.0: respond 415 if the Content-Type is the JSON:API media type
  * with any media type parameters. A missing or different Content-Type is
- * also answered with 415, since that is the only type the server accepts.
+ * also answered with 415, since that is the only type a resource accepts.
  *
- * @private
+ * A plain route (`json`) takes any JSON body, so `application/json` (with
+ * any parameters, such as `charset`) is accepted there too.
+ *
+ * @internal
  */
-export default function validateContentType(contentType?: string): true;
+export default function validateContentType(contentType?: string, { json }?: {
+    json?: boolean;
+}): true;

package/dist/types/packages/testing/audit-visibility.d.ts

@@ -0,0 +1,189 @@
+import type Application from '../application';
+/**
+ * Which records of one type a request may see, for {@link auditVisibility}:
+ * every one (`true`), the ids listed, or the ids a function accepts.
+ */
+export type VisibleRecords = true | ReadonlyArray<string | number> | ((id: string) => boolean);
+/** The options of {@link auditVisibility}. */
+export type AuditVisibilityOptions = {
+    /**
+     * The namespace to audit: `''` (the default) for the root, `'admin'` for
+     * `/admin`. Nested namespaces are audited on their own.
+     */
+    namespace?: string;
+    /**
+     * What the request may see, keyed by type. Written by hand, independently
+     * of the app's visibility rules: it is what they are checked against. A
+     * type left out may not appear at all.
+     */
+    visible: Record<string, VisibleRecords>;
+    /**
+     * Headers sent with every request, such as the `Authorization` of the user
+     * the audit is for.
+     */
+    headers?: Record<string, string>;
+    /**
+     * The ids to request each type's routes with (`GET /posts/:id`,
+     * `/posts/:id/comments`, …), keyed by type: visible and hidden ones
+     * alike. A type left out is requested with every id in the database, so
+     * keep the database small or list the ids.
+     */
+    ids?: Record<string, ReadonlyArray<string | number>>;
+    /**
+     * Query parameters a read requires, keyed by the type it serves: they are
+     * sent with that type's list, its records by id, and every related
+     * endpoint that serves it (`/posts/:id/comments` serves `comments`, and
+     * takes the parameters of the comments' controller). Relationship
+     * endpoints take none.
+     *
+     * ```javascript
+     * query: { comments: { fromDate: '2026-01-01' } }
+     * ```
+     */
+    query?: Record<string, Record<string, string>>;
+    /**
+     * Where the application is served, when not by `app` itself: a server
+     * started as a separate process (`lumen serve`), such as
+     * `'http://localhost:4000'`. `app` still provides the routes, the
+     * include paths and the ids, so it must be booted in the test, but need
+     * not listen.
+     */
+    origin?: string;
+    /**
+     * Called with each document a read answers with, for checks beyond which
+     * records appear, such as the fields a request may see of each. Return a
+     * message, or several, for each problem found: each is reported as a
+     * violation of that request. May be async.
+     *
+     * ```javascript
+     * onDocument({ document }) {
+     *   return document.included
+     *     ?.filter(({ type, attributes }) => type === 'users' && attributes.email)
+     *     .map(({ id }) => `users ${id} shows its email`);
+     * }
+     * ```
+     */
+    onDocument?: (response: AuditedDocument) => DocumentCheckResult | Promise<DocumentCheckResult>;
+};
+/**
+ * The read a request was made to, as the route defines it: so a check need
+ * not parse the URL to know which record it is about.
+ */
+export type AuditedRoute = {
+    /** The action, as hooks see it. */
+    action: 'index' | 'show' | 'showRelationship' | 'showRelated';
+    /**
+     * The route's resource type: for a relationship or related endpoint, the
+     * owner's (`posts` for `/posts/3/comments`).
+     */
+    type: string;
+    /**
+     * The id in the URL: the record of a `show`, the owner of a relationship
+     * or related endpoint. None for a list.
+     */
+    id?: string;
+    /** The relationship of a relationship or related endpoint (`comments`). */
+    relationship?: string;
+};
+/** A document a read answered with, for `onDocument`. */
+export type AuditedDocument = {
+    /** The request, as a path and query string. */
+    url: string;
+    /** Its status. */
+    status: number;
+    /** The read the request was made to. */
+    route: AuditedRoute;
+    /** The parsed JSON:API document. */
+    document: Record<string, unknown>;
+};
+/**
+ * What `onDocument` returns: a message for each problem found, or nothing
+ * when there is none.
+ */
+export type DocumentCheckResult = string | ReadonlyArray<string> | null | undefined | void;
+/**
+ * A record a response contained that the audit's `visible` does not allow; a
+ * relationship or related endpoint that answered for an owner `visible` does
+ * not allow; a request that failed with an error other than `401`, `403` or
+ * `404`, so that what it serves could not be checked; or a problem
+ * `onDocument` found.
+ */
+export type VisibilityViolation = {
+    /** The request, as a path and query string. */
+    url: string;
+    /** Its status. */
+    status: number;
+    /**
+     * The record's type, if the violation is a record: one the response named,
+     * or the hidden owner an endpoint answered for.
+     */
+    type?: string;
+    /** The record's id, if the violation is a record. */
+    id?: string;
+    /**
+     * What is wrong, for a hidden owner an endpoint answered for and for what
+     * `onDocument` found.
+     */
+    message?: string;
+};
+/** What {@link auditVisibility} found. */
+export type VisibilityAudit = {
+    /** Every request made, as a path and query string. */
+    requests: Array<string>;
+    /** What should not have been in a response, in request order. */
+    violations: Array<VisibilityViolation>;
+    /**
+     * Every record the responses named, keyed by type: as primary data,
+     * included or as linkage, allowed or not, each id once. Compare it with
+     * what the request should see to check that the audit reached it all.
+     */
+    seen: Record<string, Array<string>>;
+};
+/**
+ * Request every read a namespace serves — each list, each record by id, each
+ * relationship and related endpoint, without `include` and with every path
+ * it accepts, following every page — and report each record in a response that
+ * `visible` does not allow: in `data`, in `included`, or in any
+ * relationship's linkage. A relationship or related endpoint that answers
+ * for an owner `visible` does not allow is reported too, whatever it
+ * answers with: that it answers reveals the owner. A `401`, `403` or `404`
+ * (for a hidden record) reveals nothing and passes; any other error is
+ * reported, since the read it answers went unchecked.
+ *
+ * Visibility rules apply to every one of these paths, but scoping in an
+ * `index` or `show` override, or in a hook keyed on the action, does not.
+ * This checks the result rather than the mechanism, against a list written
+ * by hand:
+ *
+ * ```javascript
+ * import { auditVisibility } from 'lumen-framework/testing';
+ *
+ * it('shows a member only public posts and their comments', async () => {
+ *   const { violations } = await auditVisibility(app, {
+ *     namespace: 'members',
+ *     headers: { Authorization: `Bearer ${memberToken}` },
+ *     visible: {
+ *       posts: [publicPost.id],
+ *       comments: [commentOnPublicPost.id],
+ *       users: true
+ *     }
+ *   });
+ *
+ *   expect(violations).toEqual([]);
+ * });
+ * ```
+ *
+ * Requests are made one at a time, to `app` itself (which must then be
+ * listening, as {@link startApp} leaves it) or to `origin`. Custom routes are
+ * not requested. Each route is requested once per
+ * id (and per page), so run it against a small fixture database, or narrow
+ * the ids with `ids`.
+ *
+ * @param app - The application, listening.
+ * @param options - What to audit, and what the request may see.
+ * @returns Every request made, every violation found, and every record
+ * seen.
+ * @throws When the namespace serves no reads, so a mistyped namespace cannot
+ * pass by checking nothing.
+ */
+export default function auditVisibility(app: Application, { namespace, visible, headers, ids, query: required, origin, onDocument }: AuditVisibilityOptions): Promise<VisibilityAudit>;

package/dist/types/packages/testing/index.d.ts

@@ -0,0 +1,4 @@
+export { default as auditVisibility } from './audit-visibility';
+export { default as startApp } from './start-app';
+export type { StartAppOptions, StartedApp } from './start-app';
+export type { AuditedDocument, AuditedRoute, AuditVisibilityOptions, DocumentCheckResult, VisibilityAudit, VisibilityViolation, VisibleRecords } from './audit-visibility';

package/dist/types/packages/testing/start-app.d.ts

@@ -0,0 +1,52 @@
+import type Application from '../application';
+/** The options of {@link startApp}. */
+export type StartAppOptions = {
+    /**
+     * The environment to boot in: which `config/environments/*.js` and which
+     * entry of `config/database.js` apply. Sets `NODE_ENV` when given, and
+     * defaults it to `'test'` when unset, until `close()` restores it.
+     */
+    env?: string;
+    /** The port to listen on. `0`, the default, takes a free one. */
+    port?: number;
+};
+/** An application {@link startApp} booted. */
+export type StartedApp = {
+    /** The application, for {@link auditVisibility} and the models. */
+    app: Application;
+    /** Where it listens, such as `'http://localhost:53017'`. */
+    origin: string;
+    /**
+     * Stops the server, closes the database connections, and restores
+     * `NODE_ENV` to what it was before `startApp()`.
+     */
+    close: () => Promise<void>;
+};
+/**
+ * Boot the app at `path` in the test's own process, from its compiled
+ * bundle (`dist/bundle.js`), and listen on a free port.
+ *
+ * ```javascript
+ * import { startApp } from 'lumen-framework/testing';
+ *
+ * let app, origin, close;
+ *
+ * beforeAll(async () => {
+ *   ({ app, origin, close } = await startApp(process.cwd()));
+ * });
+ *
+ * afterAll(() => close());
+ * ```
+ *
+ * The bundle must be compiled for the environment first, as `lumen build`
+ * and the `lumen db:*` commands do. Its model classes are set up once per
+ * process, so start an app once and share it between test files; starting
+ * the same one again throws. `NODE_ENV` holds the app's environment until
+ * `close()`.
+ *
+ * @param path - The app's root directory.
+ * @param options - The environment and port.
+ * @returns The application, where it listens, and how to stop it.
+ * @throws When the app at `path` was already started in this process.
+ */
+export default function startApp(path: string, { env, port }?: StartAppOptions): Promise<StartedApp>;

package/dist/types/packages/testing/utils/identifiers-in.d.ts

@@ -0,0 +1,14 @@
+/** A resource's `type` and `id`. */
+export type Identifier = {
+    type: string;
+    id: string;
+};
+/**
+ * Every resource a JSON:API document names: its primary data, its `included`
+ * resources, and the linkage of each one's relationships. A relationship
+ * endpoint's primary data is linkage itself, so it is covered the same way.
+ * Ids are strings, as JSON:API sends them.
+ *
+ * @internal
+ */
+export default function identifiersIn(document: unknown): Array<Identifier>;

package/dist/types/testing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Helpers for an app's tests, imported from `lumen-framework/testing`. They
+ * are kept out of the main entry, so they never reach an app's runtime
+ * bundle.
+ *
+ * @module lumen-framework/testing
+ */
+export { auditVisibility, startApp } from './packages/testing';
+export type { AuditedDocument, AuditedRoute, AuditVisibilityOptions, DocumentCheckResult, StartAppOptions, StartedApp, VisibilityAudit, VisibilityViolation, VisibleRecords } from './packages/testing';

package/dist/types/utils/chalk.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The framework's chalk instance — equivalent to chalk's default export, which
+ * is itself a `Chalk` built without options (same colour-level detection).
+ *
+ * Built from the *named* `Chalk` export on purpose. chalk is ESM-only from v5
+ * on, and the app compiler re-bundles `dist/index.mjs` to CommonJS. Importing
+ * from an ES module, esbuild gives a default import Node's CommonJS semantics
+ * (the whole `require()` result), and `require()` of an ES module returns its
+ * namespace — so `import chalk from 'chalk'` would make `chalk.yellow`
+ * undefined inside an app. Named imports resolve correctly either way. An
+ * ESLint rule keeps the default import out of `src/`.
+ *
+ * @private
+ */
+declare const chalk: import("chalk").ChalkInstance;
+export default chalk;

package/dist/types/utils/pick.d.ts

@@ -3,8 +3,8 @@
  *
  * The result is `Partial<T>` rather than Flow's `T`: keys may be dropped, both
  * because the caller asked for a subset and because undefined values are
- * filtered out. The cast is confined to the return, where the dynamic key
- * access makes the shape unknowable to the compiler.
+ * filtered out. The casts are confined to the boundaries, where the dynamic
+ * key access makes the shape unknowable to the compiler.
  *
  * @private
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumen-framework",
-  "version": "3.1.1",
+  "version": "4.0.0",
   "description": "Build scalable, Node.js-powered REST APIs with almost no code.",
   "keywords": [
     "mvc",
@@ -15,7 +15,10 @@
   "bugs": {
     "url": "https://github.com/nickschot/lux/issues"
   },
-  "repository": "github:nickschot/lux",
+  "repository": {
+    "type": "git",
+    "url": "github:nickschot/lux"
+  },
   "license": "MIT",
   "author": "Nick Schot <nickschot@gmail.com>",
   "contributors": [
@@ -27,6 +30,19 @@
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "module": "./dist/index.mjs",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/types/testing.d.ts",
+      "module": "./dist/testing.mjs",
+      "default": "./dist/testing.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "lumen": "bin/lumen"
   },
@@ -37,46 +53,58 @@
     "LICENSE"
   ],
   "dependencies": {
-    "ansi-regex": "^5.0.1",
-    "chalk": "^4.1.2",
-    "commander": "^2.20.3",
-    "esbuild": "^0.28.1",
+    "chalk": "^6.0.1",
+    "commander": "^15.0.0",
+    "esbuild": "^0.28.2",
     "fb-watchman": "^2.0.2",
-    "inflection": "^1.13.4",
+    "inflection": "^3.0.2",
     "knex": "^3.3.0",
-    "ora": "^5.4.1"
+    "ora": "^9.4.1"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.5",
-    "@types/inflection": "1.13.2",
-    "@types/node": "^20.19.43",
-    "@vitest/coverage-v8": "^4.1.10",
-    "eslint": "^9.39.5",
+    "@eslint/js": "^10.0.1",
+    "@faker-js/faker": "^10.6.0",
+    "@types/node": "^22.20.5",
+    "@vitest/coverage-v8": "^5.0.3",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
-    "faker": "4.1.0",
-    "globals": "^17.7.0",
+    "globals": "^17.13.0",
     "lumen-framework": "link:.",
-    "node-fetch": "^2.7.0",
-    "prettier": "^3.9.5",
-    "release-plan": "^0.18.0",
-    "shx": "^0.3.4",
-    "sinon": "2.2.0",
+    "prettier": "^3.9.9",
+    "release-plan": "^0.20.1",
+    "shx": "^0.4.0",
+    "sinon": "22.1.0",
+    "typedoc": "^0.28.20",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.64.0",
-    "vitest": "^4.1.10"
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^5.0.3"
   },
   "engines": {
-    "node": ">= 20"
+    "node": ">= 22.14"
   },
-  "volta": {
-    "node": "20.20.2"
+  "devEngines": {
+    "runtime": [
+      {
+        "name": "node",
+        "version": "22.23.3",
+        "onFail": "download"
+      },
+      {
+        "name": "node",
+        "version": ">=22.14",
+        "onFail": "warn"
+      }
+    ]
   },
   "scripts": {
     "build": "node build.mjs",
     "build:debugger": "node test/utils/debugger/build.mjs",
     "build:types": "tsc -p tsconfig.build.json",
-    "clean": "shx rm -rf coverage dist test/test-app/dist",
+    "clean": "shx rm -rf coverage dist docs/api test/test-app/dist",
     "debugger": "node --enable-source-maps test/utils/debugger/dist/debug.js",
+    "docs:api": "typedoc",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "eslint .",

package/dist/types/packages/cli/commands/test.d.ts

@@ -1,4 +0,0 @@
-/**
- * @private
- */
-export declare function test(): Promise<void>;

package/dist/types/packages/logger/utils/sql.d.ts

@@ -1,4 +0,0 @@
-/**
- * @private
- */
-export default function sql(strings: readonly string[], ...values: unknown[]): string;

package/dist/types/packages/router/route/params/parameter-group/utils/has-required-params.d.ts

@@ -1,5 +0,0 @@
-import type ParameterGroup from '../index';
-/**
- * @private
- */
-export default function hasRequiredParams(group: ParameterGroup, params: Record<string, unknown>): boolean;

package/dist/types/utils/create-query-string.d.ts

@@ -1,6 +0,0 @@
-/**
- * A replacement for querystring.stringify that supports nested objects.
- *
- * @private
- */
-export default function createQueryString(src: Record<string, unknown>, prop?: string): string;

package/dist/types/utils/has-own-property.d.ts

@@ -1 +0,0 @@
-export default function hasOwnProperty(target: object, key: string): boolean;