lumen-framework 3.0.0

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

@@ -0,0 +1,521 @@
+import type { Model, ModelClass } from '../database';
+import type { JSONAPI$Document, JSONAPI$DocumentLinks, JSONAPI$ResourceObject, JSONAPI$RelationshipObject } from '../jsonapi';
+import type { Serializer$opts } from './interfaces';
+/**
+ * ## Overview
+ *
+ * The Serializer class is used to describe which attributes and relationships
+ * to include for a particular resource.
+ *
+ * The attributes and relationships you declare in a Serializer will determine
+ * the attributes and relationships that will be included in the response from
+ * the resource that the Serializer represents.
+ *
+ * #### Attributes
+ *
+ * You can add attributes to your serializer using an array assigned to the
+ * class property `attributes` like the example below.
+ *
+ * ```javascript
+ * class UsersSerializer extends Serializer {
+ *   attributes = [
+ *     'name',
+ *     'email',
+ *     'username',
+ *     'createdAt',
+ *     'updatedAt'
+ *   ];
+ * }
+ * ```
+ *
+ * Since the attributes required for a resource are declared ahead of time in a
+ * Serializer, Lumen will optimize SQL queries for the resource to only include
+ * what the Serializer needs to build the response.
+ *
+ * ```javascript
+ * import { Serializer } from 'lumen-framework';
+ *
+ * class PostsSerializer extends Serializer {
+ *   attributes = [
+ *     'body',
+ *     'title',
+ *     'createdAt'
+ *   ];
+ * }
+ *
+ * export default PostsSerializer;
+ * ```
+ *
+ * The Serializer above would result in resources returned from the `/posts`
+ * endpoint to only include the `body`, `title`, and `createdAt` attributes. If
+ * we wanted include an additional attribute such as `isPublic`, we would have
+ * to add `'isPublic'` to the `attributes` property.
+ *
+ * ```javascript
+ * import { Serializer } from 'lumen-framework';
+ *
+ * class PostsSerializer extends Serializer {
+ *   attributes = [
+ *     'body',
+ *     'title',
+ *     'isPublic',
+ *     'createdAt'
+ *   ];
+ * }
+ *
+ * export default PostsSerializer;
+ * ```
+ *
+ * #### Associations
+ *
+ * Similar to `attributes` you can declare associations by adding relationship
+ * names to either the `hasOne` or `hasMany` property arrays on a Serializer.
+ *
+ * Serializers are not concerned with ownership when it comes to associations,
+ * so both `hasOne` and `belongsTo` associations can be specified in the
+ * `hasOne` array property.
+ *
+ * ```javascript
+ * import { Model } from 'lumen-framework';
+ *
+ * class Post extends Model {
+ *  static hasOne = {
+ *    image: {
+ *      inverse: 'post'
+ *    }
+ *  };
+ *
+ *  static hasMany = {
+ *    tags: {
+ *      inverse: 'posts',
+ *      through: 'categorization'
+ *    },
+ *
+ *    comments: {
+ *      inverse: 'post'
+ *    }
+ *  };
+ *
+ *  static belongsTo = {
+ *    user: {
+ *      inverse: 'posts'
+ *    }
+ *  };
+ * }
+ *
+ * export default Post;
+ * ```
+ *
+ * To include the `user` and `image` associations in the response returned from
+ * the `/posts` endpoint, we must specify both associations in the `hasOne`
+ * property array of the Serializer.
+ *
+ * ```javascript
+ * import { Serializer } from 'lumen-framework';
+ *
+ * class PostsSerializer extends Serializer {
+ *  hasOne = [
+ *    'user',
+ *    'image'
+ *  ];
+ * }
+ *
+ * export default PostsSerializer;
+ * ```
+ *
+ * If we wanted to also include the `tags` and `comments` in the response, we
+ * have to add a `hasMany` array property containing `'tags'` and `'comments'`.
+ *
+ * ```javascript
+ * import { Serializer } from 'lumen-framework';
+ *
+ * class PostsSerializer extends Serializer {
+ *  hasOne = [
+ *    'user',
+ *    'image'
+ *  ];
+ *
+ *  hasMany = [
+ *    'tags',
+ *    'comments'
+ *  ];
+ * }
+ *
+ * export default PostsSerializer;
+ * ```
+ *
+ * You no longer need to specify that `tags` is a many to many relationship
+ * using the `Categorization` model as a join table.
+ *
+ * #### Including Related Resources
+ *
+ * When requesting related resources for an endpoint, the included resource will
+ * follow the serialization rules defined by the included resources Serializer.
+ *
+ * If we request that the `posts` association is included from the `/users`
+ * endpoint, we will only get the `attributes` that the `PostsSerializer` has
+ * defined even though the response is processed by the `UsersSerializer`.
+ *
+ * #### Sparse Fieldsets
+ *
+ * When a request specifies the fields that it would like included in the
+ * response, the fields **MUST** be declared in the `attributes` property array
+ * of the resources Serializer, or they will be ignored.
+ *
+ * #### Namespaces
+ *
+ * When using namespaces, you are not required to have a Serializer for each
+ * resource as long as a Serializer for the given resource can be resolved
+ * upstream.
+ *
+ * For example, if you have a `posts` resource and you decide to implement an
+ * admin namespace, you only need to export an `AdminPostsSerializer` from
+ * `app/serializers/admin/posts.js` if you want to specify different attributes
+ * or relationships than the `PostsSerializer` exported from
+ * `app/serializers/posts.js`.
+ *
+ * In the event that you do want to specify different attributes or
+ * relationships that the `PostsSerializer` exported from
+ * `app/serializers/posts.js`, you are not required to extend `PostsSerializer`.
+ *
+ * ```javascript
+ * import { Serializer } from 'lumen-framework';
+ *
+ * class PostsSerializer extends Serializer {
+ *   attributes = [
+ *     'body',
+ *     'title',
+ *     'createdAt'
+ *   ];
+ *
+ *   hasOne = [
+ *     'user',
+ *     'image'
+ *   ];
+ *
+ *   hasMany = [
+ *     'tags',
+ *     'comments'
+ *   ];
+ * }
+ *
+ * export default PostsSerializer;
+ * ```
+ *
+ * To add the `isPublic` attribute to the response payload of requests to a
+ * `/admin/posts` endpoint we can do either of the following examples:
+ *
+ * ```javascript
+ * // app/serializers/admin/posts.js
+ * import PostsSerializer from 'app/serializers/posts';
+ *
+ * class AdminPostsSerializer extends PostsSerializer {
+ *   attributes = [
+ *     'body',
+ *     'title',
+ *     'isPublic',
+ *     'createdAt'
+ *   ];
+ * }
+ *
+ * export default AdminPostsSerializer;
+ * ```
+ *
+ * OR
+ *
+ * ```javascript
+ * // app/serializers/admin/posts.js
+ * import { Serializer } from 'lumen-framework';
+ *
+ * class AdminPostsSerializer extends Serializer {
+ *   attributes = [
+ *     'body',
+ *     'title',
+ *     'isPublic',
+ *     'createdAt'
+ *   ];
+ *
+ *   hasOne = [
+ *     'user',
+ *     'image'
+ *   ];
+ *
+ *   hasMany = [
+ *     'tags',
+ *     'comments'
+ *   ];
+ * }
+ *
+ * export default AdminPostsSerializer;
+ * ```
+ *
+ * Even with inheritance, the examples above are a tad repetitive. We can
+ * improve this code by exporting constants from `app/serializers/posts.js`.
+ *
+ * ```javascript
+ * import { Serializer } from 'lumen-framework';
+ *
+ * export const HAS_ONE = [
+ *   'user',
+ *   'image'
+ * ];
+ *
+ * export const HAS_MANY = [
+ *   'tags',
+ *   'comments'
+ * ];
+ *
+ * export const ATTRIBUTES = [
+ *   'body',
+ *   'title',
+ *   'createdAt'
+ * ];
+ *
+ * class PostsSerializer extends Serializer {
+ *   hasOne = HAS_ONE;
+ *   hasMany = HAS_MANY;
+ *   attributes = ATTRIBUTES;
+ * }
+ *
+ * export default PostsSerializer;
+ * ```
+ *
+ * If we choose to use inheritance, our code can look like this:
+ *
+ * ```javascript
+ * // app/serializers/admin/posts.js
+ * import PostsSerializer, { ATTRIBUTES } from 'app/serializers/posts';
+ *
+ * class AdminPostsSerializer extends PostsSerializer {
+ *   attributes = [
+ *     ...ATTRIBUTES,
+ *     'isPublic'
+ *   ];
+ * }
+ *
+ * export default AdminPostsSerializer;
+ * ```
+ *
+ * If we choose not use inheritance, our code can look like this:
+ *
+ * ```javascript
+ * // app/serializers/admin/posts.js
+ * import { Serializer } from 'lumen-framework';
+ * import { HAS_ONE, HAS_MANY, ATTRIBUTES } from 'app/serializers/posts';
+ *
+ * class AdminPostsSerializer extends PostsSerializer {
+ *   hasOne = HAS_ONE;
+ *   hasMany = HAS_MANY;
+ *
+ *   attributes = [
+ *     ...ATTRIBUTES,
+ *     'isPublic'
+ *   ];
+ * }
+ *
+ * export default AdminPostsSerializer;
+ * ```
+ *
+ * @class Serializer
+ * @public
+ */
+declare class Serializer<T extends Model> {
+    /**
+     * An Array of the `hasOne` or `belongsTo` relationships on a Serializer
+     * instance's Model to include in the
+     * `relationships` resource object of a serialized payload.
+     *
+     * ```javascript
+     * class PostsSerializer extends Serializer {
+     *   hasOne = [
+     *     'user'
+     *   ];
+     * }
+     * ```
+     *
+     * @property hasOne
+     * @type {Array}
+     * @default []
+     * @public
+     */
+    hasOne: Array<string>;
+    /**
+     * An Array of the `hasMany` relationships on a Serializer instance's Model to
+     * include in the `relationships` resource object of a serialized payload.
+     *
+     * ```javscript
+     * class PostsSerializer extends Serializer {
+     *   hasMany = [
+     *     'comments'
+     *   ];
+     * }
+     * ```
+     *
+     * @property hasMany
+     * @type {Array}
+     * @default []
+     * @public
+     */
+    hasMany: Array<string>;
+    /**
+     * An array of the `attributes` on a Serializer instance's Model to include in
+     * the `attributes` resource object of a serialized payload.
+     *
+     * ```javscript
+     * class PostsSerializer extends Serializer {
+     *   attributes = [
+     *     'body',
+     *     'title'
+     *   ];
+     * }
+     * ```
+     *
+     * @property attributes
+     * @type {Array}
+     * @default []
+     * @public
+     */
+    attributes: Array<string>;
+    /**
+     * The resolved Model that a Serializer instance represents.
+     *
+     * @property model
+     * @type {Model}
+     * @private
+     */
+    model: ModelClass<T>;
+    /**
+     * A reference to the root Serializer for the namespace that a Serializer
+     * instance is a member of.
+     *
+     * @property parent
+     * @type {?Serializer}
+     * @private
+     */
+    parent: Serializer<Model> | null;
+    /**
+     * The namespace that a Serializer instance is a member of.
+     *
+     * @property namespace
+     * @type {String}
+     * @private
+     */
+    namespace: string;
+    constructor({ model, parent, namespace }: Serializer$opts<T>);
+    /**
+     * Transform an array of Model instances or a single Model instance into a
+     * [JSON API](http://jsonapi.org) document object.
+     *
+     * @method format
+     *
+     * @param {Object} options - An options object used for building the
+     * returned [JSON API](http://jsonapi.org) document object.
+     *
+     * @param {Model|Array} options.data - The Model instance or array of
+     * Model instances to transform into the returned [JSON API](
+     * http://jsonapi.org) document object.
+     *
+     * @param {Object} options.links - An object containing links to include in
+     * the top level links object of the returned [JSON API](http://jsonapi.org)
+     * document object.
+     *
+     * @param {String} options.domain - A string used to build links included in
+     * the resource and relationship objects in the returned [JSON API](
+     * http://jsonapi.org) document object.
+     *
+     * @param {Array} options.include - An array of strings containing the
+     * relationship keys that should be added to the top level included object of
+     * the returned [JSON API](http://jsonapi.org) document object.
+     *
+     * @return {Promise} Resolves with a [JSON API](http://jsonapi.org) document
+     * object.
+     *
+     * @private
+     */
+    format({ data, links, domain, include }: {
+        data: T | Array<T>;
+        links: JSONAPI$DocumentLinks;
+        domain: string;
+        include: Array<string>;
+    }): Promise<JSONAPI$Document>;
+    /**
+     * Transform a single Model instance into a [JSON API](http://jsonapi.org)
+     * resource object.
+     *
+     * @method formatOne
+     *
+     * @param {Object} options - An options object used for building the returned
+     * [JSON API](http://jsonapi.org) resource object.
+     *
+     * @param {Model} options.item - The Model instance to transform into the
+     * returned [JSON API](http://jsonapi.org) resource object.
+     *
+     * @param {Object} options.links - An object containing links to include in
+     * the top level links object of the returned [JSON API](http://jsonapi.org)
+     * resource object.
+     *
+     * @param {String} options.domain - A string used to build links included in
+     * the top level links object or relationship links objects in the returned
+     * [JSON API](http://jsonapi.org) resource object.
+     *
+     * @param {Array} options.include - An array of strings containing the
+     * relationship keys that should be added to the top level included object of
+     * a [JSON API](http://jsonapi.org) document object.
+     *
+     * @param {Array} options.included - An array of [JSON API](
+     * http://jsonapi.org) resource objects that will be added to the top level
+     * included array of a [JSON API](http://jsonapi.org) document object.
+     *
+     * @param {Boolean} options.formatRelationships - Wether or not
+     * relationships should be formatted and included in the returned
+     * [JSON API](http://jsonapi.org) resource object.
+     *
+     * @return {Promise} Resolves with a [JSON API](http://jsonapi.org) resource
+     * object.
+     *
+     * @private
+     */
+    formatOne({ item, links, domain, include, included, formatRelationships }: {
+        item: T;
+        links?: boolean;
+        domain: string;
+        include: Array<string>;
+        included: Array<JSONAPI$ResourceObject>;
+        formatRelationships?: boolean;
+    }): Promise<JSONAPI$ResourceObject>;
+    /**
+     * Transform a single Model instance into a [JSON API](http://jsonapi.org)
+     * relationship object.
+     *
+     * @method formatRelationship
+     *
+     * @param {Object} options - An options object used for building the returned
+     * [JSON API](http://jsonapi.org) relationship object.
+     *
+     * @param {Model} options.item - The Model instance to transform into the
+     * returned [JSON API](http://jsonapi.org) relationship object.
+     *
+     * @param {String} options.domain - A string used to build links included in
+     * the returned [JSON API](http://jsonapi.org) relationship object.
+     *
+     * @param {Array} options.include - An array of strings containing the
+     * relationship keys that should be added to the top level included object of
+     * a [JSON API](http://jsonapi.org) document object.
+     *
+     * @param {Array} options.included - An array of [JSON API](
+     * http://jsonapi.org) resource objects that will be added to the top level
+     * included array of a [JSON API](http://jsonapi.org) document object.
+     *
+     * @return {Promise} Resolves with a [JSON API](http://jsonapi.org)
+     * relationship object.
+     *
+     * @private
+     */
+    formatRelationship({ item, domain, include, included }: {
+        item: Model;
+        domain: string;
+        include: boolean;
+        included: Array<JSONAPI$ResourceObject>;
+    }): Promise<JSONAPI$RelationshipObject>;
+}
+export default Serializer;

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

@@ -0,0 +1,7 @@
+import type Serializer from './index';
+import type { Model, ModelClass } from '../database';
+export type Serializer$opts<T extends Model> = {
+    model: ModelClass<T>;
+    parent: Serializer<Model> | null;
+    namespace: string;
+};

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

@@ -0,0 +1,2 @@
+export declare const HAS_BODY: RegExp;
+export declare const STATUS_CODES: Map<number, string>;

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

@@ -0,0 +1,27 @@
+import type { Writable } from 'stream';
+import type { IncomingMessage, Server as HTTPServer } from 'http';
+import type Logger from '../logger';
+import type Router from '../router';
+import type { Request } from './request/interfaces';
+import type { Response } from './response/interfaces';
+import type { Server$opts, Server$cors } from './interfaces';
+/**
+ * @private
+ */
+declare class Server {
+    logger: Logger;
+    router: Router;
+    cors: Server$cors;
+    instance: HTTPServer;
+    constructor({ logger, router, cors }: Server$opts);
+    listen(port: number): void;
+    initializeRequest(req: IncomingMessage, res: Writable): [Request, Response];
+    validateRequest({ method, headers }: Request): true;
+    receiveRequest: (req: IncomingMessage, res: Writable) => void;
+}
+export default Server;
+export { REQUEST_METHODS, getDomain } from './request';
+export { default as createServerError } from './utils/create-server-error';
+export type { Server$config } from './interfaces';
+export type { Request, Request$params, Request$method } from './request/interfaces';
+export type { Response } from './response/interfaces';

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

@@ -0,0 +1,18 @@
+import type Logger from '../logger';
+import type Router from '../router';
+export type Server$cors = {
+    enabled: boolean;
+    origin?: string;
+    headers?: Array<string>;
+    methods?: Array<string>;
+};
+export type Server$config = {
+    cors: Server$cors;
+};
+export type Server$opts = Server$config & {
+    logger: Logger;
+    router: Router;
+};
+export interface Server$Error extends Error {
+    statusCode: number;
+}

package/dist/types/packages/server/request/constants.d.ts

@@ -0,0 +1,2 @@
+import type { Request$method } from './interfaces';
+export declare const REQUEST_METHODS: Array<Request$method>;

package/dist/types/packages/server/request/index.d.ts

@@ -0,0 +1,8 @@
+import type { Request, Request$opts } from './interfaces';
+/**
+ * @private
+ */
+export declare function createRequest(req: any, { logger, router }: Request$opts): Request;
+export { REQUEST_METHODS } from './constants';
+export { parseRequest } from './parser';
+export { default as getDomain } from './utils/get-domain';

package/dist/types/packages/server/request/interfaces.d.ts

@@ -0,0 +1,63 @@
+import type { Readable } from 'stream';
+import type { Socket } from 'net';
+import type Logger from '../../logger';
+import type Router from '../../router';
+import type { Route } from '../../router';
+import type Controller from '../../controller';
+export type Request$opts = {
+    logger: Logger;
+    router: Router;
+};
+type Request$url = {
+    protocol?: string;
+    slashes?: boolean;
+    auth?: string;
+    host?: string;
+    port?: string;
+    hostname?: string;
+    hash?: string;
+    search?: string;
+    params: Array<string>;
+    query: Record<string, unknown>;
+    pathname: string;
+    path: string;
+    href: string;
+};
+export type Request$method = 'GET' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'POST' | 'DELETE';
+export type Request$params = {
+    id: number | string | Buffer;
+    sort: string;
+    filter: Record<string, unknown>;
+    fields: Record<string, unknown>;
+    include: Array<string>;
+    page: {
+        size?: number;
+        number?: number;
+    };
+    data: {
+        id: number | string | Buffer;
+        type: string;
+        attributes?: Record<string, unknown>;
+        relationships?: Record<string, unknown>;
+    };
+};
+export interface Request extends Readable {
+    headers: Map<string, string>;
+    httpVersion: string;
+    method: Request$method;
+    trailers: Record<string, unknown>;
+    socket: Socket;
+    logger: Logger;
+    params: Request$params;
+    defaultParams: Request$params;
+    route: Route;
+    action: string;
+    controller: Controller;
+    url: Request$url;
+    connection: {
+        encrypted: boolean;
+        remoteAddress: string;
+    };
+    setTimeout(msecs: number, callback: () => void): void;
+}
+export {};

package/dist/types/packages/server/request/parser/constants.d.ts

@@ -0,0 +1,6 @@
+export declare const INT: RegExp;
+export declare const NULL: RegExp;
+export declare const BOOL: RegExp;
+export declare const DATE: RegExp;
+export declare const TRUE: RegExp;
+export declare const BRACKETS: RegExp;

package/dist/types/packages/server/request/parser/errors/index.d.ts

@@ -0,0 +1 @@
+export { default as MalformedRequestError } from './malformed-request-error';

package/dist/types/packages/server/request/parser/errors/malformed-request-error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @private
+ */
+declare class MalformedRequestError extends SyntaxError {
+    constructor();
+}
+declare const _default: new (...args: Array<any>) => MalformedRequestError & import("../../../interfaces").Server$Error;
+export default _default;

package/dist/types/packages/server/request/parser/index.d.ts

@@ -0,0 +1,5 @@
+import type { Request } from '../interfaces';
+/**
+ * @private
+ */
+export declare function parseRequest(req: Request): Promise<Record<string, unknown>>;

package/dist/types/packages/server/request/parser/utils/format.d.ts

@@ -0,0 +1,17 @@
+import type { Request$method } from '../../interfaces';
+/**
+ * @private
+ */
+export declare function formatSort(sort: string): string;
+/**
+ * @private
+ */
+export declare function formatFields(fields: Record<string, unknown>): Record<string, unknown>;
+/**
+ * @private
+ */
+export declare function formatInclude(include: string | Array<string>): Array<string>;
+/**
+ * @private
+ */
+export default function format(params: Record<string, unknown>, method: Request$method): Record<string, unknown>;