libcors
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    libcors, of course

    npm version build status coverage status Language grade: JavaScript Bundle size

    CORS handling, 100% transportation agnostic. Is bundled with TypeScript type information.

    This package is heavily influenced by corser for its logic. It is more or less hand-translated from corser line by line into TypeScript and by removing the dependencies on req/res.

    Motivation

    Of the other libraries out there handling CORS, cors, corser, koa-cors etc, none of them are pure CORS related, but are coupled with express or koa or Node.js' http modules, and they potentially alter the corresponding req and res objects.

    This package provides purely the logic for CORS.

    There is no mutable global state being stored within this module. Each instance you create contains its own state. Expect no magic.

    It's written in TypeScript. Exported as JavaScript with separate typings.

    API

    The package exports one function; setup.

    This function initializes a new CORS context given a set of options (if any). The return value is a function that can be called with a method and a set of headers to return (a promise to) CORS properties.

    import { setup as setupCors } from 'libcors'
    
    const corsFn = setupCors( /* optional options object */ );
    
    // We get these from somewhere:
    const method;  // 'GET', 'POST', etc
    const headers; // key-value of strings
    const corsResult = await corsFn( method, headers );

    Don't forget that corsFn returns a promise which needs to be awaited.

    Options

    The options which can be provided to setup are

    {
        origins: Origins;              // see below
        methods: string[];             // ['GET', 'HEAD', 'POST']
        requestHeaders: string[];      // see below
        responseHeaders: string[];     // see below
        supportsCredentials: boolean;  // default: false
        maxAge: number;                // default: null
        endPreflightRequests: boolean; // default: true
    }

    The origins is either an array of strings or a function taking the Origin header as argument (a string) and returns a boolean (or a promise to a boolean).

    The requestHeaders defaults to [ "accept", "accept-language", "content-language", "content-type" ] and responseHeaders defaults to [ "cache-control", "content-language", "content-type", "expires", "last-modified", "pragma" ].

    Result

    The corsResult above is defined by the TypeScript interface CorsResult:

    interface CorsResult
    {
        headers: { [ key: string ]: string; };
        vary: string[];
        status?: number; // Response code, if the request should be ended
    }

    The headers is a key-value lookup of headers that should be sent back in the response and the vary is a list of fields that should be appended to the Vary header.

    If status is defined, this means the response should be sent immediately (without allowing further middlewares/routes) and the HTTP response code should be set to this value. if ( !status ), the normal route flow should continue.

    Usage as a middleware

    The package is 100% transport/framework agnostic, so to use it as a middleware in a framework, a wrapping package should be used instead where this provides the pure logic.

    For Express, use express-libcors.

    Install

    npm i libcors

    DownloadsWeekly Downloads

    119

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    16 kB

    Total Files

    4

    Last publish

    Collaborators

    • grantila