lumen-framework 3.1.1 → 4.0.0

package/dist/types/packages/controller/interfaces.d.ts

@@ -1,13 +1,28 @@
 import type { Model, ModelClass, Query } from '../database';
 import type { Request, Response } from '../server';
 import type Serializer from '../serializer';
-export type Controller$opts = {
+/**
+ * What Lumen constructs a controller with when the app boots. Apps don't
+ * construct controllers themselves.
+ */
+export type ControllerOptions = {
+    /** The model of the controller's resource, if it has one. */
     model?: ModelClass<Model>;
+    /** The controller's namespace (`admin`), or `''` for the root. */
     namespace?: string;
+    /** The serializer of the controller's resource, if it has one. */
     serializer?: Serializer<Model>;
 };
-export type Controller$builtIn = 'show' | 'index' | 'create' | 'update' | 'destroy';
-export type Controller$beforeAction = (request: Request, response: Response) => Promise<unknown>;
-export type Controller$afterAction = (request: Request, response: Response, responseData?: unknown) => Promise<unknown>;
-export type Controller$findOne<T extends Model> = (request: Request) => Query<T>;
-export type Controller$findMany<T extends Model> = (request: Request) => Query<Array<T>>;
+export type BuiltInAction = 'show' | 'index' | 'create' | 'update' | 'destroy';
+/**
+ * A {@link Controller.beforeAction} hook. Resolving with anything but
+ * `undefined` ends the request, with that value as the response.
+ */
+export type BeforeAction = (request: Request, response: Response) => Promise<unknown>;
+/**
+ * A {@link Controller.afterAction} hook. `responseData` is the action's result
+ * (or the previous hook's); what the hook resolves with is sent instead.
+ */
+export type AfterAction = (request: Request, response: Response, responseData?: unknown) => Promise<unknown>;
+export type FindOne<T extends Model> = (request: Request) => Query<T>;
+export type FindMany<T extends Model> = (request: Request) => Query<Array<T>>;

package/dist/types/packages/controller/utils/find-many.d.ts

@@ -1,7 +1,4 @@
 import type { Model, ModelClass, Query } from '../../database';
-import type Serializer from '../../serializer';
 import type { Request } from '../../server';
-/**
- * @private
- */
-export default function findMany<T extends Model>(model: ModelClass<T>, req: Request, serializerFor?: (model: ModelClass) => Serializer<Model>): Query<Array<Model>>;
+/** @internal */
+export default function findMany<T extends Model>(model: ModelClass<T>, req: Request): Query<Array<Model>>;

package/dist/types/packages/controller/utils/find-one.d.ts

@@ -1,7 +1,4 @@
 import type { Model, ModelClass, Query } from '../../database';
-import type Serializer from '../../serializer';
 import type { Request } from '../../server';
-/**
- * @private
- */
-export default function findOne<T extends Model>(model: ModelClass<T>, req: Request, serializerFor?: (model: ModelClass) => Serializer<Model>): Query<T>;
+/** @internal */
+export default function findOne<T extends Model>(model: ModelClass<T>, req: Request): Query<T>;

package/dist/types/packages/controller/utils/params-to-query.d.ts

@@ -1,21 +1,19 @@
-import type { Model, ModelClass } from '../../database';
-import type Serializer from '../../serializer';
-import type { Request$params } from '../../server';
-type Controller$query = {
+import type { ModelClass } from '../../database';
+import type { RequestParams } from '../../server';
+type ControllerQuery = {
     id?: number | string | Buffer;
     filter?: Record<string, unknown>;
     select: Array<string>;
     page?: number;
     limit?: number;
     sort?: [string, string];
-    include: Record<string, Array<string>>;
 };
 /**
- * `serializerFor` resolves the Serializer an included resource is serialized
- * with — in the request's namespace (`Controller#serializerFor()`) — so its
- * attributes are the ones loaded. Defaults to the related model's root one.
+ * Translate request params into the primary query. Only primary data is
+ * loaded by it: resource linkage and included resources are batch-loaded by
+ * the Serializer.
  *
- * @private
+ * @internal
  */
-export default function paramsToQuery(model: ModelClass, { id, page, sort, filter, fields, include }: Request$params, serializerFor?: (related: ModelClass) => Serializer<Model>): Controller$query;
+export default function paramsToQuery(model: ModelClass, { id, page, sort, filter, fields }: RequestParams): ControllerQuery;
 export {};

package/dist/types/packages/controller/utils/resolve-relationships.d.ts

@@ -1,5 +1,3 @@
 import type { Model, ModelClass } from '../../database';
-/**
- * @private
- */
+/** @internal */
 export default function resolveRelationships<T extends Model>(model: ModelClass<T>, relationships?: Record<string, unknown>): Record<string, unknown>;

package/dist/types/packages/controller/utils/validate-relationships.d.ts

@@ -1,8 +1,10 @@
+import { Scope } from '../visibility';
 import type { Model, ModelClass } from '../../database';
 /**
  * Check that every resource referenced from `data.relationships` exists, so a
- * write cannot leave dangling linkage. One query per relationship.
+ * write cannot leave dangling linkage, or link a record `scope` hides. One
+ * query per relationship.
  *
- * @private
+ * @internal
  */
-export default function validateRelationships<T extends Model>(model: ModelClass<T>, relationships?: Record<string, unknown>): Promise<void>;
+export default function validateRelationships<T extends Model>(model: ModelClass<T>, relationships?: Record<string, unknown>, scope?: Scope): Promise<void>;

package/dist/types/packages/controller/visibility/errors.d.ts

@@ -0,0 +1,21 @@
+import type { ModelClass } from '../../database';
+/**
+ * Thrown at boot for visibility rules that cannot be applied: rules declared
+ * on a controller other than a namespace's `ApplicationController`, rules for
+ * an unknown type, or a rule that is not a function.
+ *
+ * @internal
+ */
+export declare class VisibilityConfigError extends TypeError {
+    constructor(problems: Array<string>);
+}
+/**
+ * Thrown while serving a request when a visibility rule does something other
+ * than narrow its query with conditions. A programming error, so it surfaces
+ * as a `500`.
+ *
+ * @internal
+ */
+export declare class VisibilityRuleError extends TypeError {
+    constructor({ resourceName }: ModelClass, problem: string);
+}

package/dist/types/packages/controller/visibility/index.d.ts

@@ -0,0 +1,51 @@
+import { Query } from '../../database';
+import type { Model, ModelClass } from '../../database';
+import type { Request } from '../../server';
+/**
+ * A namespace's visibility rules: per resource type, a function that narrows
+ * a `Query` of that type to the rows the request may see.
+ */
+export type Visibility = Record<string, (query: Query<Array<Model>>, request: Request) => Query<Array<Model>>>;
+/**
+ * Applies a namespace's visibility rules for one request. Every query Lumen
+ * issues for the request — primary data, linkage, `included`, relationship
+ * checks on writes — goes through `apply()`.
+ *
+ * @internal
+ */
+export declare class Scope {
+    /**
+     * Applies no rules. The default wherever no request is involved.
+     */
+    static readonly none: Scope;
+    private readonly rules;
+    private readonly request;
+    private readonly compiled;
+    constructor(rules: Visibility, request: Request | null);
+    /**
+     * Whether a rule narrows `model`.
+     */
+    covers(model: ModelClass): boolean;
+    /**
+     * Add the conditions of `query.model`'s rule, if it has one, to `query`.
+     *
+     * The conditions are added untagged, so `query.unscope()` cannot remove
+     * them.
+     */
+    apply<Q extends Query<unknown>>(query: Q): Q;
+    /**
+     * Run `model`'s rule once per request against an empty probe query and keep
+     * the conditions it adds. Only conditions are allowed: the same rule has to
+     * hold for `count()`, for the narrow selects linkage is loaded with and for
+     * existence checks, which a `select`, `order`, `limit`, `include` or join
+     * would break.
+     */
+    private conditionsFor;
+}
+/**
+ * The `Scope` of `request` under `rules`, created once per request so each
+ * rule runs at most once however many queries it narrows.
+ *
+ * @internal
+ */
+export declare function scopeFor(rules: Visibility, request: Request): Scope;

package/dist/types/packages/database/attribute/index.d.ts

@@ -1,6 +1,4 @@
-import type { Attribute$meta } from './interfaces';
-/**
- * @private
- */
-export declare function createAttribute(opts: Attribute$meta): PropertyDescriptor;
-export type { Attribute$meta } from './interfaces';
+import type { AttributeMeta } from './interfaces';
+/** @internal */
+export declare function createAttribute(opts: AttributeMeta): PropertyDescriptor;
+export type { AttributeMeta } from './interfaces';

package/dist/types/packages/database/attribute/interfaces.d.ts

@@ -1,4 +1,4 @@
-export type Attribute$meta = {
+export type AttributeMeta = {
     key: string;
     type: string;
     nullable: boolean;

package/dist/types/packages/database/attribute/utils/create-attribute.d.ts

@@ -1,5 +1,3 @@
-import type { Attribute$meta } from '../index';
-/**
- * @private
- */
-export default function createAttribute(opts: Attribute$meta): PropertyDescriptor;
+import type { AttributeMeta } from '../index';
+/** @internal */
+export default function createAttribute(opts: AttributeMeta): PropertyDescriptor;

package/dist/types/packages/database/attribute/utils/create-getter.d.ts

@@ -1,3 +1,3 @@
 import type Model from '../../model';
-import type { Attribute$meta } from '../index';
-export default function createGetter({ key, defaultValue }: Attribute$meta): (this: Model) => unknown;
+import type { AttributeMeta } from '../index';
+export default function createGetter({ key, defaultValue }: AttributeMeta): (this: Model) => unknown;

package/dist/types/packages/database/attribute/utils/create-setter.d.ts

@@ -1,8 +1,6 @@
 import type Model from '../../model';
-import type { Attribute$meta } from '../index';
-/**
- * @private
- */
-export default function createSetter({ key, nullable, normalize, defaultValue }: Attribute$meta & {
+import type { AttributeMeta } from '../index';
+/** @internal */
+export default function createSetter({ key, nullable, normalize, defaultValue }: AttributeMeta & {
     normalize: (value: unknown) => unknown;
 }): (this: Model, value?: unknown) => void;

package/dist/types/packages/database/constants.d.ts

@@ -1,4 +1,5 @@
 export declare const UNIQUE_CONSTRAINT_CODES: Set<string>;
 export declare const UNIQUE_CONSTRAINT: RegExp;
+export declare const SQLITE_DRIVER = "better-sqlite3";
 export declare const VALID_DRIVERS: string[];
 export declare const TYPE_ALIASES: Map<string, string>;

package/dist/types/packages/database/errors/index.d.ts

@@ -3,3 +3,4 @@ export { default as ModelMissingError } from './model-missing-error';
 export { default as MigrationsPendingError } from './migrations-pending-error';
 export { default as UniqueConstraintError } from './unique-constraint-error';
 export { default as ConfigMissingError } from './config-missing-error';
+export { default as RelationshipConfigError } from './relationship-config-error';

package/dist/types/packages/database/errors/invalid-driver-error.d.ts

@@ -1,6 +1,4 @@
-/**
- * @private
- */
+/** @internal */
 declare class InvalidDriverError extends Error {
     constructor(driver: string);
 }

package/dist/types/packages/database/errors/migrations-pending-error.d.ts

@@ -1,6 +1,4 @@
-/**
- * @private
- */
+/** @internal */
 declare class MigrationsPendingError extends Error {
     constructor(migrations?: Array<string>);
 }

package/dist/types/packages/database/errors/model-missing-error.d.ts

@@ -1,6 +1,4 @@
-/**
- * @private
- */
+/** @internal */
 declare class ModelMissingError extends Error {
     constructor(name: string);
 }

package/dist/types/packages/database/errors/relationship-config-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Thrown at boot when relationships are declared in a way that cannot work,
+ * listing every problem.
+ *
+ * @internal
+ */
+declare class RelationshipConfigError extends TypeError {
+    constructor(problems: Array<string>);
+}
+export default RelationshipConfigError;

package/dist/types/packages/database/errors/unique-constraint-error.d.ts

@@ -1,4 +1,4 @@
 declare class UniqueConstraintError extends Error {
 }
-declare const _default: new (...args: Array<any>) => UniqueConstraintError & import("../../server/interfaces").Server$Error;
+declare const _default: new (...args: Array<any>) => UniqueConstraintError & import("../../server").ServerError;
 export default _default;

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

@@ -1,9 +1,7 @@
 import type { Knex } from 'knex';
 import type Logger from '../logger';
-import type { Database$opts, ModelClass } from './interfaces';
-/**
- * @private
- */
+import type { DatabaseOptions, ModelClass } from './interfaces';
+/** @internal */
 declare class Database {
     path: string;
     debug: boolean;
@@ -12,15 +10,20 @@ declare class Database {
     schema: () => Knex.SchemaBuilder;
     connection: Knex;
     models: Map<string, ModelClass>;
-    constructor(opts: Database$opts);
+    constructor(opts: DatabaseOptions);
     modelFor(type: string): ModelClass;
 }
 export default Database;
 export { default as Model } from './model';
 export { default as Query } from './query';
+export { readAttribute, writeAttribute } from './model/utils/attribute';
 export { default as Migration, generateTimestamp } from './migration';
 export { default as connect } from './utils/connect';
 export { default as typeForColumn } from './utils/type-for-column';
+export { default as primaryKeyType } from './utils/primary-key-type';
 export { default as createMigrations } from './utils/create-migrations';
 export { default as pendingMigrations } from './utils/pending-migrations';
-export type { Database$opts, Database$config, ModelClass } from './interfaces';
+export type { DatabaseOptions, DatabaseConfig, DatabaseEnvironmentConfig, DatabasePoolConfig, ModelClass } from './interfaces';
+export type { ModelHook, ModelHooks } from './model/interfaces';
+export type { RelationshipOptions } from './relationship/interfaces';
+export type { TransactionResult } from './transaction/interfaces';

package/dist/types/packages/database/initialize.d.ts

@@ -1,6 +1,4 @@
 import type Database from './index';
-import type { Database$opts } from './index';
-/**
- * @private
- */
-export default function initialize<T extends Database>(instance: T, opts: Database$opts): Promise<T>;
+import type { DatabaseOptions } from './index';
+/** @internal */
+export default function initialize<T extends Database>(instance: T, opts: DatabaseOptions): Promise<T>;

package/dist/types/packages/database/interfaces.d.ts

@@ -2,84 +2,174 @@ import type Logger from '../logger';
 import type Serializer from '../serializer';
 import type Database from './index';
 import type { Model, Query } from './index';
-import type { Model$Hooks } from './model/interfaces';
-import type { Relationship$opts } from './relationship/interfaces';
-import type { Transaction$ResultProxy } from './transaction/interfaces';
-type Database$pool = number | {
+import type { ModelHooks } from './model/interfaces';
+import type { RelationshipOptions } from './relationship/interfaces';
+import type { TransactionResult } from './transaction/interfaces';
+/**
+ * The size of the connection pool, per process: a maximum (the minimum is
+ * then 2, or 1 for a pool of 1), or both bounds.
+ */
+export type DatabasePoolConfig = number | {
+    /** The fewest connections kept open. */
     min: number;
+    /** The most connections open at once. */
     max: number;
 };
-type Database$columnType = 'floating' | 'enu' | 'bool' | 'varchar' | 'bigInteger';
-export type Database$environment = {
+type DatabaseColumnType = 'floating' | 'enu' | 'bool' | 'varchar' | 'bigInteger';
+/**
+ * The database connection of one environment, in `config/database.js`.
+ *
+ * ```javascript
+ * production: {
+ *   driver: 'pg',
+ *   host: 'db.internal',
+ *   database: 'blog_prod',
+ *   username: 'blog',
+ *   password: process.env.DATABASE_PASSWORD,
+ *   pool: 10
+ * }
+ * ```
+ *
+ * A `url`, or the `DATABASE_URL` environment variable, replaces the host,
+ * credentials and database settings; `driver`, `pool`, `debug` and `ssl`
+ * still apply.
+ */
+export type DatabaseEnvironmentConfig = {
+    /** The database server's host name. */
     host?: string;
-    pool?: Database$pool;
+    /** The connection pool size, per process. */
+    pool?: DatabasePoolConfig;
+    /**
+     * Log every SQL statement, with its values, at `DEBUG`. Defaults to `true`
+     * in development only.
+     */
     debug?: boolean;
+    /** The client: `'pg'`, `'mysql2'` or `'better-sqlite3'`. */
     driver: string;
+    /** A Unix socket to connect through instead of `host` and `port`. */
     socket?: string;
+    /**
+     * The database name. With SQLite, the file is
+     * `db/<database>_<NODE_ENV>.sqlite` in the app.
+     */
     database?: string;
+    /** The user to connect as. */
     username?: string;
+    /** The user's password. */
     password?: string;
+    /** The database server's port. */
     port?: number;
-    ssl?: boolean;
+    /**
+     * Connect over TLS: `true`, or the driver's TLS options
+     * (`{ rejectUnauthorized: false }` for a certificate Node doesn't trust,
+     * as on Heroku Postgres). Applies with a `url` or `DATABASE_URL` too,
+     * unless the URL sets TLS itself (`?sslmode=…`).
+     */
+    ssl?: boolean | Record<string, unknown>;
+    /**
+     * A connection string (`postgres://user:pass@host:5432/db`) that replaces
+     * the host, credentials and database settings. `DATABASE_URL` takes
+     * precedence over it.
+     */
     url?: string;
 };
-export type Database$config = {
-    development: Database$environment;
-    test: Database$environment;
-    production: Database$environment;
+/**
+ * The contents of `config/database.js`: a connection per environment,
+ * chosen by `NODE_ENV` or the CLI's `--environment`.
+ */
+export type DatabaseConfig = {
+    /** The connection used by `lumen serve` and the `db:` commands by default. */
+    development: DatabaseEnvironmentConfig;
+    /** The connection used when `NODE_ENV` is `test`. */
+    test: DatabaseEnvironmentConfig;
+    /** The connection used when `NODE_ENV` is `production`. */
+    production: DatabaseEnvironmentConfig;
+    [environment: string]: DatabaseEnvironmentConfig | undefined;
 };
-export type Database$opts = {
+export type DatabaseOptions = {
     path: string;
     models: Map<string, ModelClass>;
-    config: Database$config;
+    config: DatabaseConfig;
     logger: Logger;
     checkMigrations?: boolean;
+    checkRelationships?: boolean;
 };
-export type Database$column = {
-    type: Database$columnType;
+export type DatabaseColumn = {
+    type: DatabaseColumnType;
     nullable: boolean;
     maxLength: string;
     columnName: string;
     defaultValue: unknown;
 };
 /**
- * The static-bearing model *class* (`Class<Model>` in the original Flow). The
- * `Model` base class and its subclasses satisfy this structurally; it is the
- * type app-facing code (controllers, serializers, the router) refers to when it
- * holds "a model class".
+ * A model class — {@link Model} or a subclass — as a value: what
+ * `Post` is, where a `Post` record is a {@link Model}. Framework APIs that
+ * take or return a model use it.
  */
 export interface ModelClass<T extends Model = Model> {
+    /** @internal */
     new (attrs?: Record<string, unknown>, initialize?: boolean): T;
+    /** @internal */
     prototype: T;
+    /** The class name (`BlogPost`). */
     name: string;
+    /** See {@link Model.primaryKey}. */
     primaryKey: string;
+    /** See {@link Model.tableName}. */
     tableName: string;
+    /** See {@link Model.modelName}. */
     modelName: string;
+    /** See {@link Model.resourceName}. */
     resourceName: string;
+    /** @internal */
     serializer: Serializer<T>;
+    /** @internal */
     attributes: Record<string, unknown>;
+    /** @internal */
     attributeNames: Array<string>;
-    relationships: Record<string, Relationship$opts>;
+    /** @internal */
+    relationships: Record<string, RelationshipOptions>;
+    /** @internal */
     relationshipNames: Array<string>;
+    /** See {@link Model.hasOne}. */
     hasOne: Record<string, unknown>;
+    /** See {@link Model.hasMany}. */
     hasMany: Record<string, unknown>;
+    /** See {@link Model.belongsTo}. */
     belongsTo: Record<string, unknown>;
+    /** See {@link Model.scopes}. */
     scopes: Record<string, unknown>;
+    /** See {@link Model.validates}. */
     validates: Record<string, unknown>;
-    hooks: Model$Hooks;
+    /** See {@link Model.hooks}. */
+    hooks: ModelHooks;
+    /** @internal */
     store: Database;
+    /** See {@link Model.logger}. */
     logger: Logger;
+    /** @internal */
     table(): any;
+    /** See {@link Model.isInstance}. */
     isInstance(value: unknown): boolean;
+    /** @internal */
     initialize(store: Database, table: () => unknown): Promise<ModelClass>;
+    /** See {@link Model.transaction}. */
     transaction<R>(fn: (...args: Array<unknown>) => Promise<R>): Promise<R>;
-    columnFor(key: string): Database$column | undefined;
+    /** @internal */
+    columnFor(key: string): DatabaseColumn | undefined;
+    /** @internal */
     columnNameFor(key: string): string | undefined;
-    relationshipFor(key: string): Relationship$opts | undefined;
+    /** @internal */
+    relationshipFor(key: string): RelationshipOptions | undefined;
+    /** See {@link Model.find}. */
     find(primaryKey: unknown): Query<T>;
+    /** See {@link Model.first}. */
     first(): Query<T>;
+    /** See {@link Model.where}. */
     where(conditions: Record<string, unknown>): Query<Array<T>>;
+    /** See {@link Model.select}. */
     select(...columns: Array<string>): Query<Array<T>>;
-    create(attributes?: Record<string, unknown>, trx?: unknown): Promise<Transaction$ResultProxy<T, boolean>>;
+    /** See {@link Model.create}. */
+    create(attributes?: Record<string, unknown>, trx?: unknown): Promise<TransactionResult<T, boolean>>;
 }
 export {};

package/dist/types/packages/database/migration/index.d.ts

@@ -1,12 +1,10 @@
-import type { Migration$Fn } from './interfaces';
-/**
- * @private
- */
+import type { MigrationFn } from './interfaces';
+/** @internal */
 declare class Migration<T extends object> {
-    fn: Migration$Fn<T>;
-    constructor(fn: Migration$Fn<T>);
+    fn: MigrationFn<T>;
+    constructor(fn: MigrationFn<T>);
     run(schema: T): T;
 }
 export default Migration;
 export { default as generateTimestamp } from './utils/generate-timestamp';
-export type { Migration$Fn } from './interfaces';
+export type { MigrationFn } from './interfaces';

package/dist/types/packages/database/migration/interfaces.d.ts

@@ -1,4 +1,2 @@
-/**
- * @private
- */
-export type Migration$Fn<T extends object> = (schema: T) => T;
+/** @internal */
+export type MigrationFn<T extends object> = (schema: T) => T;

package/dist/types/packages/database/migration/utils/generate-timestamp.d.ts

@@ -1,2 +1,10 @@
 export declare function padding(char: string, amount: number): Generator<string, void, void>;
-export default function generateTimestamp(): string;
+/**
+ * A migration's version: `YYYYMMDDHHmmssCC` in UTC (`CC` are hundredths of a
+ * second), 16 digits. Fixed-width and zero-padded, so versions sort in the
+ * order they were generated — `lumen db:migrate` runs migrations in that
+ * order.
+ *
+ * @private
+ */
+export default function generateTimestamp(now?: Date): string;