Logo for jsDocs.io

editions

  • Version 6.22.0
  • Published
  • 144 kB
  • 1 dependency
  • Artistic-2.0 license

Install

npm i editions
yarn add editions
pnpm add editions

Overview

Publish multiple editions for your JavaScript packages consistently and easily (e.g. source edition, esnext edition, es2015 edition)

Index

Functions

Interfaces

Type Aliases

Functions

function assertEdition

assertEdition: (edition: unknown) => asserts edition is Edition;

  • Asserts that the the Edition has all the required properties.

    Parameter edition

    The Edition to validate

    Throws

    if invalid

function assertEditions

assertEditions: (editions: unknown) => asserts editions is Editions;

  • Asserts that the provided Editions array is valid and non-empty.

    Parameter editions

    The Editions array to validate

    Throws

    if editions is missing, not an array, or empty

function determineEdition

determineEdition: (editions: Editions, opts: VersionOptions) => Edition;

  • Determine which edition should be loaded. If VersionOptions.broadenRange is unspecified (the default behavior), then we attempt to determine a suitable edition without broadening the range, and if that fails, then we try again with the range broadened.

    Parameter editions

    The array of editions to choose from

    Parameter opts

    The version options containing environment versions and range settings

    Returns

    any suitable editions

    Throws

    if no suitable editions

function isCompatibleEdition

isCompatibleEdition: (edition: Edition, opts: VersionOptions) => true;

  • Checks that the Edition is compatible against the provided versions.

    Parameter edition

    The edition to check for compatibility

    Parameter opts

    The version options containing environment versions and range settings

    Returns

    if compatible

    Throws

    if incompatible

function isCompatibleEngines

isCompatibleEngines: (engines: Engines, opts: VersionOptions) => true;

  • Checks that the provided engines are compatible against the provided versions.

    Parameter engines

    The engine specifications to check compatibility for

    Parameter opts

    The version options containing environment versions and range settings

    Returns

    if compatible

    Throws

    if incompatible

function isCompatibleVersion

isCompatibleVersion: (range: Range, version: string, opts: RangeOptions) => true;

  • Is this Edition suitable for these versions?

    Parameter range

    The version range to check compatibility against

    Parameter version

    The actual version to check

    Parameter opts

    The range options for configuring how ranges are handled

    Returns

    if compatible

    Throws

    if incompatible

function isValidEdition

isValidEdition: (edition: Edition) => true;

  • Verify the Edition has all the required properties.

    Parameter edition

    The edition to validate

    Returns

    if valid

    Throws

    if invalid

    Deprecated

    Use isValidEdition instead.

function loadEdition

loadEdition: <T>(edition: Edition, opts: LoaderOptions) => T;

  • Load the Edition with the loader.

    Parameter edition

    The edition to load

    Parameter opts

    The loading options containing the loader function and optional path configurations

    Returns

    The result of the loaded edition.

    Throws

    If failed to load, an error is thrown with the reason.

function requirePackage

requirePackage: <T>(
    cwd: PathOptions['cwd'],
    loader: LoaderOptions['loader'],
    entry: PathOptions['entry']
) => T;

  • Cycle through the editions for a package, determine the compatible edition, and load it.

    Parameter cwd

    The current working directory path where the package.json is located

    Parameter loader

    The loader function to use for loading the selected edition

    Parameter entry

    The entry point to load from the selected edition

    Returns

    the loaded result of the suitable edition

    Throws

    if no suitable editions, or if the edition failed to load

function solicitEdition

solicitEdition: <T>(editions: Editions, opts: SolicitOptions) => T;

  • Determine which edition should be loaded, and attempt to load it.

    Parameter editions

    The array of editions to choose from

    Parameter opts

    The solicit options containing loader, versions, and path configurations

    Returns

    the loaded result of the suitable edition

    Throws

    if no suitable editions, or the edition failed to load

Interfaces

interface Edition

interface Edition {}

  • Edition entries must conform to the following specification.

    Example 1

    {
      "description": "esnext source code with require for modules",
      "directory": "source",
      "entry": "index.js",
      "tags": [
        "javascript",
        "esnext",
        "require"
      ],
      "engines": {
        "node": ">=6",
        "browsers": "defaults"
      }
    }

property debugging

debugging?: ErrorDetailed;

  • If this edition fails to load, then this property provides any accompanying information.

property description

description: string;

  • Use this property to describe the edition in human readable terms. Such as what it does and who it is for. It is used to reference the edition in user facing reporting, such messages.

    Example 1

    "esnext source code with require for modules"

property directory

directory: string;

  • The location to where this directory is located. It should be a relative path from the package.json file.

    Example 1

    "source"

property engines

engines: Engines;

  • This field is used to specific which environments this edition supports. If false this edition does not any environment. If deno is a string, it should be a semver range of Deno versions that the edition targets. If node is a string, it should be a semver range of Node.js versions that the edition targets. If browsers is a string, it should be a [browserlist](https://github.com/browserslist/browserslist) value of the specific browser values the edition targets. If multiple engines are truthy, it indicates that this edition is compatible with those multiple environments.

    Example 1

    {
      "deno": ">=1",
      "node": ">=6",
      "browsers": "defaults"
    }

property entry

entry: string;

  • The default entry location for this edition, relative to the edition's directory.

    Example 1

    "index.js"

property tags

tags?: string[];

  • Any keywords you wish to associate to the edition. Useful for various ecosystem tooling, such as automatic ESNext lint configuration if the esnext tag is present in the source edition tags.

    Example 1

    ["javascript", "esnext", "require"]

interface LoaderOptions

interface LoaderOptions extends Partial<PathOptions> {}

  • Options for loading editions, including optional path configuration and a required loader function

property loader

loader: Loader;

    interface PathOptions

    interface PathOptions {}

    • Options for specifying paths when loading editions

    property cwd

    cwd: string;

    • If provided, edition loading will be resolved against this.

    property entry

    entry: string;

    • If provided, this edition entry is used instead of the default entry.

    interface RangeOptions

    interface RangeOptions {}

    • Options for configuring how version ranges are handled

    property broadenRange

    broadenRange?: boolean;

    • If true, then ranges such as x || y are changed to >=x.

    interface SolicitOptions

    interface SolicitOptions extends LoaderOptions, VersionOptions {}

    • Combined options for soliciting (determining and loading) editions

    interface VersionOptions

    interface VersionOptions extends RangeOptions {}

    • Options that combine range configuration with version information

    property versions

    versions: Versions;

    • The versions of our current environment.

    Type Aliases

    type Editions

    type Editions = Edition[];

    • Editions should be ordered from most preferable first to least desirable last. The source edition should always be first, proceeded by compiled editions.

    type Engines

    type Engines = false | Record<string, Range>;

    • Engine specifications that can be false (unsupported) or a record of engine names to their version ranges

    type Loader

    type Loader = (this: Edition, path: string) => unknown;

    • The method that will load the entry of the edition. For CJS files this should be set to the require method. For MJS files this should be set to (path: string) => import(path).

    type Range

    type Range = string | boolean;

    • A version range specification that can be a string (semver range) or boolean (true for any version, false for none)

    type Versions

    type Versions = Record<string, string>;

    • A record of environment versions, mapping environment names to their version strings

    Package Files (1)

    Dependencies (1)

    Dev Dependencies (11)

    Peer Dependencies (0)

    No peer dependencies.

    Badge

    To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

    You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/editions.

    • Markdown
      [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/editions)
    • HTML
      <a href="https://www.jsdocs.io/package/editions"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>